> ## Documentation Index > Fetch the complete documentation index at: https://kapso-1adbad2d.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Send a WhatsApp message (standalone) > Sends a new WhatsApp message without requiring a conversation ID. This endpoint automatically finds or creates a conversation based on the phone number and WhatsApp configuration. **Configuration Selection:** - If `whatsapp_config_id` is provided, uses that specific configuration - If `customer_id` is provided, uses the customer's WhatsApp configuration - If neither is provided, uses the first available configuration for the project **Conversation Management:** - Automatically finds existing active conversations for the phone number - Creates new conversations if none exist - Updates conversation activity timestamps - Creates WhatsApp contacts as needed **Message Types:** Supports all message types including text, template, media, interactive, location, reaction, and contacts. **Agent Integration:** Respects agent execution states and handoff rules. Messages are blocked when an agent execution is active and not in handoff, failed, or stopped state. ## OpenAPI ````yaml api/legacy/openapi-whatsapp.yaml post /whatsapp_messages openapi: 3.0.3 info: title: Kapso External API - WhatsApp API description: >- API for programmatically interacting with Kapso agents, executions, and WhatsApp conversations. This specification includes only WhatsApp API endpoints. version: 1.0.0 contact: name: Kapso Support servers: - url: https://app.kapso.ai/api/v1 description: Production server security: - ApiKeyAuth: [] paths: /whatsapp_messages: post: tags: - WhatsApp Messages summary: Send a WhatsApp message (standalone) description: > Sends a new WhatsApp message without requiring a conversation ID. This endpoint automatically finds or creates a conversation based on the phone number and WhatsApp configuration. **Configuration Selection:** - If `whatsapp_config_id` is provided, uses that specific configuration - If `customer_id` is provided, uses the customer's WhatsApp configuration - If neither is provided, uses the first available configuration for the project **Conversation Management:** - Automatically finds existing active conversations for the phone number - Creates new conversations if none exist - Updates conversation activity timestamps - Creates WhatsApp contacts as needed **Message Types:** Supports all message types including text, template, media, interactive, location, reaction, and contacts. **Agent Integration:** Respects agent execution states and handoff rules. Messages are blocked when an agent execution is active and not in handoff, failed, or stopped state. operationId: sendWhatsappMessage parameters: - name: whatsapp_config_id in: query required: false schema: type: string format: uuid description: ID of the specific WhatsApp configuration to use - name: customer_id in: query required: false schema: type: string format: uuid description: ID of the customer whose WhatsApp configuration to use - name: phone_number in: query required: false schema: type: string description: >- Phone number to send the message to (can also be provided in the message object) example: '+1234567890' requestBody: required: true content: application/json: schema: type: object required: - message properties: message: type: object required: - phone_number properties: phone_number: type: string description: >- Phone number to send the message to (in international format) example: '+1234567890' content: type: string description: The message content to send (for text messages) example: Hello, how can I help you today? message_type: type: string description: The type of message enum: - text - image - video - audio - document - template - location - interactive - reaction - contacts default: text example: text media_url: type: string description: >- URL of the media file to send (for image, video, audio, document message types) media_id: type: string description: >- WhatsApp media ID to use instead of a URL (for image, video, audio, document message types) media_file: type: string format: binary description: >- Media file upload (for image, video, audio, document message types) caption: type: string description: Caption for media messages (image, video, document) filename: type: string description: Filename for document messages latitude: type: number format: float description: Latitude for location messages longitude: type: number format: float description: Longitude for location messages location_name: type: string description: Optional name for the location location_address: type: string description: Optional address for the location interactive_type: type: string enum: - button - list description: Type of interactive message body_text: type: string description: Main message text for interactive messages header_text: type: string description: Header text for interactive messages footer_text: type: string description: Footer text for interactive messages buttons: type: array description: Button definitions for button-type interactive messages items: type: object properties: id: type: string description: Button identifier title: type: string description: Button display text sections: type: array description: Section definitions for list-type interactive messages items: type: object properties: title: type: string description: Section title rows: type: array items: type: object properties: id: type: string description: Row identifier title: type: string description: Row title description: type: string description: Optional row description list_button_text: type: string description: >- Text for the button that opens the list (for list-type interactive messages) example: View Options template_name: type: string description: Name of the template to use template_language: type: string description: Language code of the template (e.g., en_US) template_params: oneOf: - type: array description: >- Array of values for positional parameters (e.g., {{1}}, {{2}}) items: type: string example: - John Smith - Tomorrow at 2 PM - type: object description: >- Object with named parameters (e.g., {{name}}, {{email}}) additionalProperties: type: string example: name: John Smith email: john@example.com description: > Parameters to fill in the template placeholders. Use array format for templates with positional parameters ({{1}}, {{2}}). Use object format for templates with named parameters ({{name}}, {{email}}). header_type: type: string description: Type of header for template messages enum: - text - image - video - document header_params: type: string description: >- Content for the template header (URL for media, text for text headers) header_filename: type: string description: Filename for document headers reaction_emoji: type: string description: Emoji to use for the reaction reacted_to_message_id: type: string description: ID of the message to react to contacts: type: array minItems: 1 maxItems: 257 description: > Contact cards to send (required for contacts messages, 1-257 per WhatsApp guidelines). At least one contact with a name is required. Supports both nested name object and flattened name keys for backward compatibility. items: type: object required: - name properties: name: type: object description: >- Contact name (either formatted_name or first_name required) properties: formatted_name: type: string description: Full formatted contact name example: Barbara J. Johnson first_name: type: string description: First name example: Barbara last_name: type: string description: Last name example: Johnson middle_name: type: string description: Middle name example: Joana prefix: type: string description: Name prefix example: Dr. suffix: type: string description: Name suffix example: Esq. birthday: type: string format: date description: Contact birthday (YYYY-MM-DD) example: '1999-01-23' addresses: type: array description: Physical addresses for the contact items: type: object properties: street: type: string description: Street address example: 1 Lucky Shrub Way city: type: string description: City example: Menlo Park state: type: string description: State or province example: CA zip: type: string description: ZIP or postal code example: '94025' country: type: string description: Country name example: United States country_code: type: string description: ISO country code example: US type: type: string description: Address type example: Office emails: type: array description: Email addresses for the contact items: type: object required: - email properties: email: type: string format: email description: Email address example: bjohnson@luckyshrub.com type: type: string description: Email type example: Work phones: type: array description: Phone numbers for the contact items: type: object required: - phone properties: phone: type: string description: >- Phone number (international format recommended) example: '+16505559999' type: type: string description: Phone number type example: Landline wa_id: type: string description: >- WhatsApp ID (normalized phone number without + prefix) example: '19175559999' org: type: object description: Organization information properties: company: type: string description: Company name example: Lucky Shrub department: type: string description: Department name example: Legal title: type: string description: Job title example: Lead Counsel urls: type: array description: URLs for the contact items: type: object required: - url properties: url: type: string format: uri description: URL example: https://www.luckyshrub.com type: type: string description: URL type example: Company examples: text_message: summary: Simple text message description: Send a basic text message value: message: phone_number: '+1234567890' content: Hello, how can I help you today? message_type: text template_message: summary: Template message with parameters description: Send a template message with parameters value: message: phone_number: '+1234567890' message_type: template template_name: order_confirmation template_params: - John Doe - ORD-12345 template_message_named: summary: Template message with named parameters description: >- Send a template message with named parameters (e.g., {{customer_name}}, {{order_id}}) value: message: phone_number: '+1234567890' message_type: template template_name: order_notification template_language: en_US template_params: customer_name: John Doe order_id: ORD-12345 delivery_date: Tomorrow at 2 PM total_amount: $99.99 with_config: summary: Message with specific WhatsApp config description: Send a message using a specific WhatsApp configuration value: whatsapp_config_id: 550e8400-e29b-41d4-a716-446655440000 message: phone_number: '+1234567890' content: Hello from specific config! message_type: text with_customer: summary: Message with customer specification description: Send a message using a customer's WhatsApp configuration value: customer_id: 550e8400-e29b-41d4-a716-446655440001 message: phone_number: '+1234567890' content: Hello from customer's config! message_type: text contacts_message: summary: Contact card message description: Send a contact card with complete information value: message: phone_number: '+1234567890' message_type: contacts contacts: - name: formatted_name: Barbara J. Johnson first_name: Barbara last_name: Johnson middle_name: Joana prefix: Dr. suffix: Esq. birthday: '1999-01-23' addresses: - street: 1 Lucky Shrub Way city: Menlo Park state: CA zip: '94025' country: United States country_code: US type: Office emails: - email: bjohnson@luckyshrub.com type: Work phones: - phone: '+16505559999' type: Landline - phone: '+19175559999' type: Mobile wa_id: '19175559999' org: company: Lucky Shrub department: Legal title: Lead Counsel urls: - url: https://www.luckyshrub.com type: Company responses: '201': description: Message created and sent successfully content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/WhatsappMessage' examples: text_message: summary: Text message response value: data: id: msg-123abc phone_number: '+1234567890' message_type: text content: Hello, how can I help you today? direction: outbound status: sent whatsapp_message_id: wamid.HBgLMTIzNDU2Nzg5MAUCAw== created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' template_message: summary: Template message response value: data: id: msg-456def phone_number: '+1234567890' message_type: template content: Hi John Doe, your order ORD-12345 has been confirmed! direction: outbound status: sent whatsapp_message_id: wamid.HBgLMTIzNDU2Nzg5MAUCAw== metadata: template_name: order_confirmation template_params: - John Doe - ORD-12345 created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' template_message_named: summary: Template message with named params response value: data: id: msg-789ghi phone_number: '+1234567890' message_type: template content: >- Hi John Doe, your order ORD-12345 totaling $99.99 will be delivered Tomorrow at 2 PM! direction: outbound status: sent whatsapp_message_id: wamid.HBgLMTIzNDU2Nzg5MAUCAw== metadata: template_name: order_notification template_language: en_US template_params: customer_name: John Doe order_id: ORD-12345 delivery_date: Tomorrow at 2 PM total_amount: $99.99 created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' template_with_header_body_named: summary: Template with named params in header and body response value: data: id: msg-101jkl phone_number: '+1234567890' message_type: template content: >- Summer Sale: Shop now through August 31st and use code SUMMER25 to get 25% off! direction: outbound status: sent whatsapp_message_id: wamid.HBgLMTIzNDU2Nzg5MAUCAw== metadata: template_name: seasonal_sale_extended template_language: en_US template_params: header: sale_name: Summer Sale body: end_date: August 31st promo_code: SUMMER25 discount_amount: 25% created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' contacts_message: summary: Contact card message response value: data: id: msg-202mno phone_number: '+1234567890' message_type: contacts content: 'Contact: Barbara J. Johnson' direction: outbound status: sent whatsapp_message_id: wamid.HBgLMTIzNDU2Nzg5MAUCAw== metadata: contacts_data: - name: formatted_name: Barbara J. Johnson first_name: Barbara last_name: Johnson middle_name: Joana prefix: Dr. suffix: Esq. birthday: '1999-01-23' addresses: - street: 1 Lucky Shrub Way city: Menlo Park state: CA zip: '94025' country: United States country_code: US type: Office emails: - email: bjohnson@luckyshrub.com type: Work phones: - phone: '+16505559999' type: Landline - phone: '+19175559999' type: Mobile wa_id: '19175559999' org: company: Lucky Shrub department: Legal title: Lead Counsel urls: - url: https://www.luckyshrub.com type: Company created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' '400': description: Bad request - missing required parameters content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing_phone: summary: Missing phone number value: error: Phone number is required '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Template not found content: application/json: schema: $ref: '#/components/schemas/Error' examples: template_not_found: summary: Template not found value: error: Template not found '409': description: Cannot send message when an agent execution is active content: application/json: schema: $ref: '#/components/schemas/Error' examples: agent_active: summary: Agent execution conflict value: error: >- Cannot send a manual message when an agent execution is active and not in handoff, failed, or stopped state '422': description: Validation error or WhatsApp configuration not found content: application/json: schema: $ref: '#/components/schemas/Error' examples: config_not_found: summary: WhatsApp configuration not found value: error: WhatsApp configuration not found '500': description: WhatsApp service error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: WhatsappMessage: type: object properties: id: type: string format: uuid phone_number: type: string message_type: type: string enum: - text - image - video - audio - document - template - location - interactive - reaction - contacts description: The type of WhatsApp message content: type: string description: Human-readable representation of the message content direction: type: string enum: - inbound - outbound status: type: string processing_status: type: string enum: - pending - processed whatsapp_message_id: type: string metadata: type: object nullable: false description: Type-specific metadata for the message media_url: type: string description: >- URL to access any attached media (for image, video, audio, document message types) message_type_data: type: object description: Type-specific data based on the message_type oneOf: - $ref: '#/components/schemas/TextMessageData' - $ref: '#/components/schemas/ImageMessageData' - $ref: '#/components/schemas/VideoMessageData' - $ref: '#/components/schemas/AudioMessageData' - $ref: '#/components/schemas/DocumentMessageData' - $ref: '#/components/schemas/LocationMessageData' - $ref: '#/components/schemas/TemplateMessageData' - $ref: '#/components/schemas/InteractiveMessageData' - $ref: '#/components/schemas/ReactionMessageData' - $ref: '#/components/schemas/ContactsMessageData' created_at: type: string format: date-time updated_at: type: string format: date-time Error: type: object properties: error: type: string example: Resource not found status: type: integer example: 404 message: type: string example: The requested resource could not be found TextMessageData: type: object description: Data specific to text messages properties: text: type: string description: The text content of the message ImageMessageData: type: object description: Data specific to image messages properties: caption: type: string description: Optional caption for the image media_id: type: string description: WhatsApp media ID for the image mime_type: type: string description: MIME type of the image (e.g., image/jpeg) VideoMessageData: type: object description: Data specific to video messages properties: caption: type: string description: Optional caption for the video media_id: type: string description: WhatsApp media ID for the video mime_type: type: string description: MIME type of the video (e.g., video/mp4) AudioMessageData: type: object description: Data specific to audio messages properties: media_id: type: string description: WhatsApp media ID for the audio mime_type: type: string description: MIME type of the audio (e.g., audio/ogg) DocumentMessageData: type: object description: Data specific to document messages properties: caption: type: string description: Optional caption for the document media_id: type: string description: WhatsApp media ID for the document mime_type: type: string description: MIME type of the document (e.g., application/pdf) filename: type: string description: Original filename of the document LocationMessageData: type: object description: Data specific to location messages properties: latitude: type: number format: float description: Latitude coordinate longitude: type: number format: float description: Longitude coordinate location_name: type: string description: Optional name for the location location_address: type: string description: Optional address for the location TemplateMessageData: type: object description: Data specific to template messages properties: template_name: type: string description: Name of the template used template_language: type: string description: Language code of the template (e.g., en_US) template_params: type: array description: Parameters used in the template items: type: string header_type: type: string description: Type of header used in the template enum: - text - image - video - document header_params: type: string description: Content for the template header header_filename: type: string description: Filename for document headers InteractiveMessageData: type: object description: Data specific to interactive messages properties: interactive_type: type: string enum: - button - list description: Type of interactive message body_text: type: string description: Main text content of the interactive message header_text: type: string description: Optional header text footer_text: type: string description: Optional footer text buttons: type: array description: Buttons for button-type interactive messages items: type: object properties: id: type: string description: Unique identifier for the button title: type: string description: Display text for the button sections: type: array description: Sections for list-type interactive messages items: type: object properties: title: type: string description: Section title rows: type: array items: type: object properties: id: type: string description: Row identifier title: type: string description: Row title description: type: string description: Optional row description reply_option_id: type: string description: For replies, the ID of the selected option reply_option_title: type: string description: For replies, the title of the selected option list_button_text: type: string description: Text for the button that opens the list (for list-type messages) ReactionMessageData: type: object description: Data specific to reaction messages properties: reaction_emoji: type: string description: Emoji used for the reaction reacted_to_message_id: type: string description: ID of the message being reacted to ContactsMessageData: type: object description: > Data specific to contact messages. Supports 1-257 contacts per WhatsApp guidelines. At least one contact with a name (formatted_name or first_name) is required. properties: contacts: type: array minItems: 1 maxItems: 257 description: List of contact cards to send items: type: object required: - name properties: name: type: object description: >- Contact name information. Either formatted_name or first_name is required. properties: formatted_name: type: string description: Full formatted contact name example: Barbara J. Johnson first_name: type: string description: First name example: Barbara last_name: type: string description: Last name example: Johnson middle_name: type: string description: Middle name example: Joana prefix: type: string description: Name prefix example: Dr. suffix: type: string description: Name suffix example: Esq. birthday: type: string format: date description: Contact birthday in YYYY-MM-DD format example: '1999-01-23' phones: type: array description: List of phone numbers items: type: object required: - phone properties: phone: type: string description: Phone number (international format recommended) example: '+16505559999' type: type: string description: Phone number type example: Mobile wa_id: type: string description: WhatsApp ID (normalized phone number without + prefix) example: '19175559999' emails: type: array description: List of email addresses items: type: object required: - email properties: email: type: string format: email description: Email address example: bjohnson@luckyshrub.com type: type: string description: Email type example: Work addresses: type: array description: List of physical addresses items: type: object properties: street: type: string description: Street address example: 1 Lucky Shrub Way city: type: string description: City example: Menlo Park state: type: string description: State or province example: CA zip: type: string description: ZIP or postal code example: '94025' country: type: string description: Country name example: United States country_code: type: string description: ISO country code example: US type: type: string description: Address type example: Office urls: type: array description: List of URLs items: type: object required: - url properties: url: type: string format: uri description: URL example: https://www.luckyshrub.com type: type: string description: URL type example: Company org: type: object description: Organization information properties: company: type: string description: Company name example: Lucky Shrub department: type: string description: Department name example: Legal title: type: string description: Job title example: Lead Counsel securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key required for all endpoints ````