> ## 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 new WhatsApp message > Sends a new message through WhatsApp Cloud API and creates the message record ## OpenAPI ````yaml api/legacy/openapi-whatsapp.yaml post /whatsapp_conversations/{conversation_id}/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_conversations/{conversation_id}/whatsapp_messages: post: tags: - WhatsApp Messages summary: Send a new WhatsApp message description: >- Sends a new message through WhatsApp Cloud API and creates the message record operationId: createWhatsappMessage parameters: - name: conversation_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - message properties: message: type: object required: - content properties: content: type: string description: The message content to send 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 (required for image/video/audio/document) example: https://example.com/image.jpg caption: type: string description: Caption for media messages example: Check out this image filename: type: string description: Filename for document messages example: document.pdf latitude: type: number format: float description: Latitude (required for location messages) example: 37.7749 longitude: type: number format: float description: Longitude (required for location messages) example: -122.4194 location_name: type: string description: Location name example: San Francisco template_name: type: string description: Template name (required for template messages) example: hello_world template_language: type: string description: Template language code (required for template messages) example: en_US template_params: type: array description: Template parameters items: type: string example: - John - Smith interactive_type: type: string enum: - button - list description: Interactive message type example: button body_text: type: string description: Interactive message body example: Choose an option buttons: type: array description: Buttons for interactive messages items: type: object properties: id: type: string example: btn_1 title: type: string example: 'Yes' 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 example: Barbara J. Johnson first_name: type: string example: Barbara last_name: type: string example: Johnson middle_name: type: string example: Joana prefix: type: string example: Dr. suffix: type: string example: Esq. birthday: type: string format: date description: Contact birthday (YYYY-MM-DD) example: '1999-01-23' addresses: type: array items: type: object properties: street: type: string example: 1 Lucky Shrub Way city: type: string example: Menlo Park state: type: string example: CA zip: type: string example: '94025' country: type: string example: United States country_code: type: string example: US type: type: string example: Office emails: type: array items: type: object required: - email properties: email: type: string format: email example: bjohnson@luckyshrub.com type: type: string example: Work phones: type: array items: type: object required: - phone properties: phone: type: string example: '+16505559999' type: type: string example: Landline wa_id: type: string example: '19175559999' org: type: object properties: company: type: string example: Lucky Shrub department: type: string example: Legal title: type: string example: Lead Counsel urls: type: array items: type: object required: - url properties: url: type: string format: uri example: https://www.luckyshrub.com type: type: string example: Company examples: text_message: summary: Simple text message value: message: content: Hello, how can I help you today? message_type: text image_message: summary: Image message value: message: content: Check out this image message_type: image media_url: https://example.com/image.jpg caption: Beautiful sunset location_message: summary: Location message value: message: content: Here's my location message_type: location latitude: 37.7749 longitude: -122.4194 location_name: San Francisco template_message: summary: Template message value: message: content: Template message message_type: template template_name: hello_world template_language: en_US template_params: - John - Smith template_message_named: summary: Template message with named parameters value: message: content: Order notification message_type: template template_name: order_update template_language: en_US template_params: customer_name: John Smith order_number: ORD-2024-001 status: shipped tracking_number: 1Z999AA1234567890 template_message_named_with_header: summary: Template with named parameters in header and body value: message: content: Promotional message message_type: template 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% interactive_button: summary: Interactive button message value: message: content: Choose an option message_type: interactive interactive_type: button body_text: 'Please select one:' buttons: - id: 'yes' title: 'Yes' - id: 'no' title: 'No' contacts_message: summary: Contact card message value: message: 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' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Conversation not found content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Cannot send message when an agent execution is active content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/Error' '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 ````