> ## Documentation Index > Fetch the complete documentation index at: https://docs.buildwithchirp.com/llms.txt > Use this file to discover all available pages before exploring further. # Send WhatsApp Message > Send a WhatsApp message (text, media, template, or interactive) ## OpenAPI ````yaml /openapi.json post /v1/whatsapp/messages openapi: 3.1.0 info: version: 1.0.0 title: Chirp API description: Communication APIs for SMS, MMS, and WhatsApp messaging servers: - url: https://api.buildwithchirp.com security: [] paths: /v1/whatsapp/messages: post: tags: - App - WhatsApp requestBody: content: application/json: schema: type: object properties: from: type: string example: '+15551234567' description: >- WhatsApp phone number to send from (must be assigned to your app) to: type: string example: '+15559876543' description: WhatsApp phone number to send to type: type: string enum: - text - image - video - audio - document - sticker - location - contacts - reaction - template - interactive example: text description: Type of message to send text: type: object properties: body: type: string example: Hello from Chirp! description: Text message body required: - body description: Text message content. Required when type is 'text' media: type: object properties: mediaId: type: string pattern: ^media_ example: media_abc123 description: >- Chirp media ID of previously uploaded media. Upload media first via POST /v1/media. caption: type: string example: Check out this image! description: >- Caption for the media (optional, supported for image, video, document) filename: type: string example: document.pdf description: Filename override for documents (optional) required: - mediaId description: >- Media content. Required when type is 'image', 'video', 'audio', or 'document'. Media must be uploaded first via POST /v1/media. sticker: type: object properties: mediaId: type: string pattern: ^media_ example: media_sticker123 description: >- Chirp media ID of sticker. Must be WebP format, max 500KB for static or 100KB for animated. required: - mediaId description: >- Sticker content. Required when type is 'sticker'. Stickers must be uploaded first via POST /v1/media. location: type: object properties: latitude: type: number example: 37.7749 description: Latitude coordinate longitude: type: number example: -122.4194 description: Longitude coordinate name: type: string example: Chirp HQ description: Location name (optional) address: type: string example: 123 Main St, San Francisco, CA description: Location address (optional) required: - latitude - longitude description: Location content. Required when type is 'location' contacts: type: object properties: contacts: type: array items: type: object properties: name: type: object properties: formattedName: type: string example: John Doe description: Full formatted name (required) firstName: type: string example: John description: First name lastName: type: string example: Doe description: Last name middleName: type: string example: Robert description: Middle name prefix: type: string example: Dr. description: Name prefix suffix: type: string example: Jr. description: Name suffix required: - formattedName description: Contact name information phones: type: array items: type: object properties: phone: type: string example: '+15551234567' description: Phone number type: type: string enum: - CELL - MAIN - IPHONE - HOME - WORK example: CELL description: Phone type required: - phone description: Phone numbers emails: type: array items: type: object properties: email: type: string format: email example: john@example.com description: Email address type: type: string enum: - HOME - WORK example: WORK description: Email type required: - email description: Email addresses addresses: type: array items: type: object properties: street: type: string example: 123 Main St city: type: string example: San Francisco state: type: string example: CA zip: type: string example: '94105' country: type: string example: United States countryCode: type: string example: US type: type: string enum: - HOME - WORK example: WORK description: Physical addresses org: type: object properties: company: type: string example: Acme Inc department: type: string example: Engineering title: type: string example: Senior Engineer description: Organization information urls: type: array items: type: object properties: url: type: string format: uri example: https://example.com type: type: string enum: - HOME - WORK example: WORK required: - url description: Website URLs birthday: type: string example: '1990-01-15' description: Birthday in YYYY-MM-DD format required: - name minItems: 1 description: Array of contacts to share (vCard format) required: - contacts description: Contacts content. Required when type is 'contacts' reaction: type: object properties: messageId: type: string example: msg_wa_2DbBs7GWhGvVNJGrDXr5RG0mBWI description: Chirp message ID (msg_wa_*) to react to emoji: type: string example: 👍 description: >- Emoji to react with. Send empty string to remove reaction. required: - messageId - emoji description: >- Reaction content. Required when type is 'reaction'. Reacts to an existing message with an emoji. template: type: object properties: name: type: string example: hello_world description: Template name as registered with WhatsApp language: type: string example: en_US description: Template language code variables: type: object additionalProperties: type: string example: '1': John '2': your order description: Template variables (key-value pairs) required: - name - language description: Template content. Required when type is 'template' interactive: type: object properties: type: type: string enum: - buttons - list - cta_url - location_request - flow example: buttons description: >- Interactive message type: buttons (max 3), list (sections with rows), cta_url (URL button), location_request (ask for location), flow (WhatsApp Flow) body: type: string example: 'Please choose an option:' description: Interactive message body text header: type: object properties: type: type: string enum: - text - image - video - document example: text description: Header type text: type: string example: Welcome! description: Header text (when type is 'text') mediaId: type: string pattern: ^media_ example: media_abc123 description: >- Chirp media ID (when type is 'image', 'video', or 'document') required: - type description: Optional header for interactive message footer: type: string example: Powered by Chirp description: Optional footer text buttons: type: array items: type: object properties: id: type: string maxLength: 256 example: btn_1 description: >- Button identifier (max 256 chars, returned in webhook) title: type: string maxLength: 20 example: Option 1 description: Button text (max 20 chars) required: - id - title maxItems: 3 description: >- Reply buttons (when type is 'buttons'). Maximum 3 buttons. buttonText: type: string maxLength: 20 example: View Options description: >- Text for the list button (when type is 'list'). Max 20 chars. sections: type: array items: type: object properties: title: type: string example: Section 1 description: Section title (required if more than 1 section) rows: type: array items: type: object properties: id: type: string maxLength: 200 example: row_1 description: >- Row identifier (max 200 chars, returned in webhook) title: type: string maxLength: 24 example: Item 1 description: Row title (max 24 chars) description: type: string maxLength: 72 example: Description of item 1 description: Row description (max 72 chars) required: - id - title minItems: 1 maxItems: 10 required: - rows maxItems: 10 description: >- Sections with rows for list-type interactive message. Max 10 sections, max 10 rows per section. url: type: string format: uri example: https://example.com/checkout description: >- URL to open when button is tapped (when type is 'cta_url') flowId: type: string example: '1234567890' description: WhatsApp Flow ID (when type is 'flow') flowToken: type: string example: flow_token_abc123 description: Flow token for session tracking (when type is 'flow') flowAction: type: string enum: - navigate - data_exchange example: navigate description: >- Flow action type (when type is 'flow'). 'navigate' for screen navigation, 'data_exchange' for data operations. flowActionPayload: type: object additionalProperties: {} example: screen: WELCOME data: user_name: John description: Initial data to pass to the flow (when type is 'flow') required: - type - body description: >- Interactive message content. Required when type is 'interactive' replyTo: type: string minLength: 1 example: msg_wa_2DbBs7GWhGvVNJGrDXr5RG0mBWI description: >- Chirp message ID (msg_wa_*) to reply to. Creates a contextual reply that displays the original message. Meta IDs (wamid.*) are not accepted. required: - from - to - type responses: '201': description: Message queued successfully content: application/json: schema: type: object properties: id: type: string pattern: ^msg_wa_(?:test_)?[a-zA-Z0-9]{27}$ example: msg_wa_2DbBs7GWhGvVNJGrDXr5RG0mBWI description: >- Unique identifier for a WhatsApp Message. Format: msg_wa_[test_]{ksuid} from: type: string to: type: string type: type: string enum: - text - image - video - audio - document - sticker - location - contacts - reaction - template - interactive status: type: string enum: - queued timestamp: type: string format: date-time required: - id - from - to - type - status - timestamp '400': description: >- Invalid request parameters Possible codes: `invalid_phone_number`, `unsupported_message_type`, `media_too_large` content: application/json: schema: $ref: '#/components/schemas/ApiError' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ApiError' '402': description: >- Message delivery failed Possible codes: `message_undeliverable`, `conversation_window_expired`, `recipient_not_on_whatsapp` content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': description: >- Phone number not found or not assigned to your app Possible codes: `phone_number_not_assigned`, `whatsapp_not_configured` content: application/json: schema: $ref: '#/components/schemas/ApiError' '424': description: >- Provider error from Meta Possible codes: `meta_api_error`, `meta_api_unavailable` content: application/json: schema: $ref: '#/components/schemas/ApiError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ApiError' security: - appAuth: [] components: schemas: ApiError: type: object properties: error: type: object properties: type: type: string enum: - invalid_request_error - authentication_error - provider_error - api_error description: The type of error returned example: invalid_request_error code: type: string enum: - message_undeliverable - conversation_window_expired - recipient_not_on_whatsapp - phone_number_not_assigned - unsupported_message_type - media_too_large - invalid_phone_number - template_not_found - template_parameter_mismatch - groups_not_eligible - account_restricted - display_name_not_approved - whatsapp_not_configured - meta_api_error - meta_api_unavailable - telnyx_api_error - telnyx_api_unavailable - rate_limit_exceeded - whatsapp_rate_limited - resource_already_exists - test_app_required - call_not_found - call_already_ended - call_failed - call_rejected - call_timeout - call_busy - calling_not_configured - calling_disabled - max_concurrent_calls_reached - recording_not_found - recording_already_in_progress - recording_failed - voicemail_not_found - voicemail_disabled - invalid_call_command - command_not_applicable - whatsapp_calling_not_enabled - whatsapp_call_permission_required - whatsapp_call_permission_limit - whatsapp_pstn_bridge_forbidden - livekit_api_error - livekit_room_error - sip_trunk_error description: A machine-readable error code for programmatic handling example: invalid_phone_number message: type: string description: Human-readable error message example: The phone number "+1abc" is not in E.164 format. doc_url: type: string format: uri description: URL to documentation for this error code example: >- https://docs.buildwithchirp.com/api_reference/error-codes#invalid_phone_number param: type: string description: The parameter that caused the error example: from provider: $ref: '#/components/schemas/ProviderError' additional_info: type: array items: type: string description: Human-readable remediation hints (e.g. from Meta Health Status). required: - type - message required: - error ProviderError: type: object properties: source: type: string enum: - meta - telnyx - livekit description: Provider name example: meta code: anyOf: - type: number - type: string description: Provider's native error code message: type: string description: Provider's error message fbtrace_id: type: string description: Meta's trace ID for support tickets health_status: $ref: '#/components/schemas/HealthStatusPayload' required: - source - code - message HealthStatusPayload: type: object properties: can_send_message: type: string enum: - AVAILABLE - LIMITED - BLOCKED description: Meta Health Status value entities: type: array items: $ref: '#/components/schemas/HealthStatusEntity' required: - can_send_message - entities description: >- Meta Health Status payload, present when the error was enriched via the Health Status API. HealthStatusEntity: oneOf: - type: object properties: entity_type: type: string enum: - PHONE_NUMBER - MESSAGE_TEMPLATE - WABA - BUSINESS - APP id: type: string can_send_message: type: string enum: - AVAILABLE can_receive_call_sip: type: string enum: - AVAILABLE - LIMITED - BLOCKED description: Meta Health Status value errors: type: array items: $ref: '#/components/schemas/HealthStatusError' required: - entity_type - id - can_send_message - type: object properties: entity_type: type: string enum: - PHONE_NUMBER - MESSAGE_TEMPLATE - WABA - BUSINESS - APP id: type: string can_send_message: type: string enum: - LIMITED can_receive_call_sip: type: string enum: - AVAILABLE - LIMITED - BLOCKED description: Meta Health Status value additional_info: type: array items: type: string errors: type: array items: $ref: '#/components/schemas/HealthStatusError' required: - entity_type - id - can_send_message - additional_info - type: object properties: entity_type: type: string enum: - PHONE_NUMBER - MESSAGE_TEMPLATE - WABA - BUSINESS - APP id: type: string can_send_message: type: string enum: - BLOCKED can_receive_call_sip: type: string enum: - AVAILABLE - LIMITED - BLOCKED description: Meta Health Status value errors: type: array items: $ref: '#/components/schemas/HealthStatusError' required: - entity_type - id - can_send_message - errors HealthStatusError: type: object properties: error_code: type: number error_description: type: string possible_solution: type: string required: - error_code - error_description - possible_solution securitySchemes: appAuth: type: http scheme: bearer description: >- App API key (format: sk_live_app_* or sk_test_app_*) for app-level operations ````