> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Send a WhatsApp message

> Send any WhatsApp message type from your own platform: templates, text, media, location, location requests, buttons, lists and link buttons. Templates stay out of the inbox until the customer replies.

One endpoint for every outbound WhatsApp message, driven from your own platform. Pick the shape with `type`; the rest of the body is that type's fields plus the shared `phone_number_id`, `contact`, `reference_id` and `idempotency_key`.

The contact must have a phone number: an unknown phone number creates the contact, while an `id` or `email` must point at an existing contact that has one.

## Templates and sessions

A `template` is the only type that can go out at any time. What happens to it depends on whether the contact already has an **open session** on that number:

* **No open session**: the template is sent and **no session opens**. Nothing shows in the inbox. When the customer replies, their session opens carrying every template sent to them that has not yet appeared on a session, oldest first, before the reply. The response says `"delivery": "hidden"`.
* **Open session**: by default the template is added to it, visibly (`"delivery": "session"`). Send `"when_session_open": "hidden"` to keep it off the timeline until the customer's next reply, which then pulls it in before the reply.

Templates to a contact on the [outbound blocklist](https://docs.open.cx/api-reference/outbound-blocklist/check.md) for WhatsApp are refused with `422` and `"error": "recipient_blocked"`. A customer who stops marketing messages from you on their device is added to that blocklist automatically.

## Every other type

Text, media, location, location requests, buttons, lists and link buttons are replies: WhatsApp only delivers them inside the contact's [24-hour reply window](https://docs.open.cx/whatsapp/whatsapp-rules.md#24-hour-reply-window), and they land on the contact's open session.

* Window closed → `422` with `"error": "reply_window_closed"`. Send a template instead.
* Window open but the session is closed → `422` with `"error": "no_open_session"`. Send a template instead; the customer's reply opens a new session.

On the timeline, buttons, lists, link buttons and locations read as text (`Do you approve?\n[Approve] [Decline]`), with the full request kept on the message. Media URLs must be public; links into private networks are refused.

## Errors from WhatsApp

When WhatsApp refuses the message, the answer carries a stable `error` code and WhatsApp's own explanation in `message`:

| Status | `error` | Meaning |
| - | - | - |
| `422` | `contact_channel_restricted`, `contact_address_blocked` | The contact asked not to be reached on WhatsApp, or the number is on the do-not-contact list. Nothing is sent; see [refused sends](https://docs.open.cx/api-reference/contacts/introduction.md#refused-sends). |
| `422` | `recipient_unreachable` | The number is not on WhatsApp, or cannot be messaged. |
| `422` | `template_pending`, `template_paused`, `template_in_appeal`, `template_disabled` | The template is not sendable in its current state. |
| `422` | `rejected_by_whatsapp`, `sender_restricted` | WhatsApp rejected the message or restricted the sender. |
| `429` | `rate_limited` | Sending too fast for this number; retry later. |
| `502` | `provider_error`, `provider_unreachable` | WhatsApp failed or could not be reached; nothing was sent. |
| `502` | `send_outcome_unknown` | The connection dropped after the request left, or WhatsApp accepted the message but its result could not be recorded; the message **may** have been delivered. See retries. |

## Retries

Send the same `idempotency_key` on a retry and you get the first result back without a second message going out. Keys are permanent per organization and the body is not compared, so key on the message (order id + event), not on the order alone.

* A key whose send WhatsApp refused is released: the retry sends.
* A key whose outcome is unknown stays taken and keeps answering `502 send_outcome_unknown`; use a new key to send again.
* A retry that overlaps the first request gets `409` with `"error": "idempotency_key_in_flight"`. A first request that never finished on our side stops blocking after 10 minutes: its key then answers `502 send_outcome_unknown` like any other unknown outcome.

`reference_id` is yours (an order id, for example): it is stored and echoed back in the response.

## Delivery

The response confirms WhatsApp accepted the message (`whatsapp_message_id`). Delivery, read and failure receipts are kept on the send for the inbox and the timeline; they are not yet readable through the API.


## OpenAPI

````yaml post /whatsapp/messages
openapi: 3.1.0
info:
  title: OpenCX API
  description: >

    OpenCX is an AI-powered, all-in-one platform for customer support and
    outbound communications.


    Use this API to manage your OpenCX organization's AI agents, actions,
    conversations, contacts, and more.


    To get started, generate a new API key from the dashboard.


    ## Authentication

    All API endpoints require authentication using a Bearer token. You can
    generate an API key from your OpenCX dashboard.


    ## Rate Limiting

    API requests are rate limited to ensure fair usage. The current limits are:

    - 100 requests per minute for standard endpoints

    - 1000 requests per minute for streaming endpoints


    ## Error Handling

    The API uses standard HTTP status codes and returns detailed error messages
    in the response body.
  version: 1.0-beta
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: http://localhost:8080
    description: Development
  - url: https://api.open.cx
    description: Production
security:
  - bearerAuth: []
paths:
  /whatsapp/messages:
    post:
      summary: Send a WhatsApp message
      description: >-
        One endpoint for every outbound WhatsApp message type, driven from your
        own platform. A template to a contact with no open session is sent
        without opening one: nothing shows in the inbox until the customer
        replies, and the reply's session then carries every template sent since,
        in order. A template to a contact with an open session lands in it (see
        `when_session_open`).
      operationId: sendWhatsappMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendWhatsappMessageInputDto'
      responses:
        '201':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendWhatsappMessageOutputDto'
        '422':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                      - 422
                  message:
                    type: string
                  error:
                    description: >-
                      contact_channel_restricted when the contact restricted
                      this channel; contact_address_blocked when the address is
                      on the do-not-contact list for this channel.
                    type: string
                required:
                  - statusCode
                  - message
                additionalProperties: false
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
components:
  schemas:
    SendWhatsappMessageInputDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/SendWhatsappMessageInputDtoInput'
      oneOf:
        - type: object
          properties:
            phone_number_id:
              type: string
              minLength: 1
              description: >-
                The WhatsApp number to send from. `GET /whatsapp/senders` lists
                them.
            contact:
              anyOf:
                - type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                      pattern: >-
                        ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  required:
                    - id
                - type: object
                  properties:
                    email:
                      type: string
                      format: email
                      pattern: >-
                        ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                  required:
                    - email
                - type: object
                  properties:
                    phone_number:
                      type: string
                  required:
                    - phone_number
              description: >-
                Who receives it, by id, email or phone number. An unknown phone
                number creates the contact; an id or email must be an existing
                contact that has a phone number.
            reference_id:
              description: >-
                Your own id for this message (an order id). Stored and echoed
                back.
              type: string
              minLength: 1
              maxLength: 255
            idempotency_key:
              description: >-
                Send the same key on a retry and the first result comes back
                without a second message going out. Keys are permanent per
                organization and the body is not compared, so key on the message
                (order id + event), not on the order. A key whose send WhatsApp
                refused is released; one whose outcome is unknown stays taken.
              type: string
              minLength: 1
              maxLength: 255
            type:
              type: string
              const: template
            template_id:
              type: string
              minLength: 1
            variables:
              type: array
              items:
                type: string
              description: 'Positional values: header placeholders, then body, then buttons.'
            header_document_filename:
              description: Name the recipient sees on a DOCUMENT header.
              type: string
              minLength: 1
            when_session_open:
              $ref: '#/components/schemas/WhatsAppTemplateWhenSessionOpen'
              default: append
              description: >-
                When the contact already has an open session on this number:
                `append` (default) puts the template in it, visibly; `hidden`
                keeps it off the timeline until the customer replies.
          required:
            - phone_number_id
            - contact
            - type
            - template_id
            - variables
        - type: object
          properties:
            phone_number_id:
              type: string
              minLength: 1
              description: >-
                The WhatsApp number to send from. `GET /whatsapp/senders` lists
                them.
            contact:
              anyOf:
                - type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                      pattern: >-
                        ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  required:
                    - id
                - type: object
                  properties:
                    email:
                      type: string
                      format: email
                      pattern: >-
                        ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                  required:
                    - email
                - type: object
                  properties:
                    phone_number:
                      type: string
                  required:
                    - phone_number
              description: >-
                Who receives it, by id, email or phone number. An unknown phone
                number creates the contact; an id or email must be an existing
                contact that has a phone number.
            reference_id:
              description: >-
                Your own id for this message (an order id). Stored and echoed
                back.
              type: string
              minLength: 1
              maxLength: 255
            idempotency_key:
              description: >-
                Send the same key on a retry and the first result comes back
                without a second message going out. Keys are permanent per
                organization and the body is not compared, so key on the message
                (order id + event), not on the order. A key whose send WhatsApp
                refused is released; one whose outcome is unknown stays taken.
              type: string
              minLength: 1
              maxLength: 255
            type:
              type: string
              const: text
            text:
              type: string
              minLength: 1
              maxLength: 4096
          required:
            - phone_number_id
            - contact
            - type
            - text
        - type: object
          properties:
            phone_number_id:
              type: string
              minLength: 1
              description: >-
                The WhatsApp number to send from. `GET /whatsapp/senders` lists
                them.
            contact:
              anyOf:
                - type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                      pattern: >-
                        ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  required:
                    - id
                - type: object
                  properties:
                    email:
                      type: string
                      format: email
                      pattern: >-
                        ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                  required:
                    - email
                - type: object
                  properties:
                    phone_number:
                      type: string
                  required:
                    - phone_number
              description: >-
                Who receives it, by id, email or phone number. An unknown phone
                number creates the contact; an id or email must be an existing
                contact that has a phone number.
            reference_id:
              description: >-
                Your own id for this message (an order id). Stored and echoed
                back.
              type: string
              minLength: 1
              maxLength: 255
            idempotency_key:
              description: >-
                Send the same key on a retry and the first result comes back
                without a second message going out. Keys are permanent per
                organization and the body is not compared, so key on the message
                (order id + event), not on the order. A key whose send WhatsApp
                refused is released; one whose outcome is unknown stays taken.
              type: string
              minLength: 1
              maxLength: 255
            type:
              type: string
              const: image
            url:
              type: string
              format: uri
              description: A public URL WhatsApp can fetch.
            caption:
              type: string
              minLength: 1
              maxLength: 1024
          required:
            - phone_number_id
            - contact
            - type
            - url
        - type: object
          properties:
            phone_number_id:
              type: string
              minLength: 1
              description: >-
                The WhatsApp number to send from. `GET /whatsapp/senders` lists
                them.
            contact:
              anyOf:
                - type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                      pattern: >-
                        ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  required:
                    - id
                - type: object
                  properties:
                    email:
                      type: string
                      format: email
                      pattern: >-
                        ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                  required:
                    - email
                - type: object
                  properties:
                    phone_number:
                      type: string
                  required:
                    - phone_number
              description: >-
                Who receives it, by id, email or phone number. An unknown phone
                number creates the contact; an id or email must be an existing
                contact that has a phone number.
            reference_id:
              description: >-
                Your own id for this message (an order id). Stored and echoed
                back.
              type: string
              minLength: 1
              maxLength: 255
            idempotency_key:
              description: >-
                Send the same key on a retry and the first result comes back
                without a second message going out. Keys are permanent per
                organization and the body is not compared, so key on the message
                (order id + event), not on the order. A key whose send WhatsApp
                refused is released; one whose outcome is unknown stays taken.
              type: string
              minLength: 1
              maxLength: 255
            type:
              type: string
              const: video
            url:
              type: string
              format: uri
              description: A public URL WhatsApp can fetch.
            caption:
              type: string
              minLength: 1
              maxLength: 1024
          required:
            - phone_number_id
            - contact
            - type
            - url
        - type: object
          properties:
            phone_number_id:
              type: string
              minLength: 1
              description: >-
                The WhatsApp number to send from. `GET /whatsapp/senders` lists
                them.
            contact:
              anyOf:
                - type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                      pattern: >-
                        ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  required:
                    - id
                - type: object
                  properties:
                    email:
                      type: string
                      format: email
                      pattern: >-
                        ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                  required:
                    - email
                - type: object
                  properties:
                    phone_number:
                      type: string
                  required:
                    - phone_number
              description: >-
                Who receives it, by id, email or phone number. An unknown phone
                number creates the contact; an id or email must be an existing
                contact that has a phone number.
            reference_id:
              description: >-
                Your own id for this message (an order id). Stored and echoed
                back.
              type: string
              minLength: 1
              maxLength: 255
            idempotency_key:
              description: >-
                Send the same key on a retry and the first result comes back
                without a second message going out. Keys are permanent per
                organization and the body is not compared, so key on the message
                (order id + event), not on the order. A key whose send WhatsApp
                refused is released; one whose outcome is unknown stays taken.
              type: string
              minLength: 1
              maxLength: 255
            type:
              type: string
              const: audio
            url:
              type: string
              format: uri
              description: A public URL WhatsApp can fetch.
          required:
            - phone_number_id
            - contact
            - type
            - url
        - type: object
          properties:
            phone_number_id:
              type: string
              minLength: 1
              description: >-
                The WhatsApp number to send from. `GET /whatsapp/senders` lists
                them.
            contact:
              anyOf:
                - type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                      pattern: >-
                        ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  required:
                    - id
                - type: object
                  properties:
                    email:
                      type: string
                      format: email
                      pattern: >-
                        ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                  required:
                    - email
                - type: object
                  properties:
                    phone_number:
                      type: string
                  required:
                    - phone_number
              description: >-
                Who receives it, by id, email or phone number. An unknown phone
                number creates the contact; an id or email must be an existing
                contact that has a phone number.
            reference_id:
              description: >-
                Your own id for this message (an order id). Stored and echoed
                back.
              type: string
              minLength: 1
              maxLength: 255
            idempotency_key:
              description: >-
                Send the same key on a retry and the first result comes back
                without a second message going out. Keys are permanent per
                organization and the body is not compared, so key on the message
                (order id + event), not on the order. A key whose send WhatsApp
                refused is released; one whose outcome is unknown stays taken.
              type: string
              minLength: 1
              maxLength: 255
            type:
              type: string
              const: document
            url:
              type: string
              format: uri
              description: A public URL WhatsApp can fetch.
            filename:
              type: string
              minLength: 1
              maxLength: 240
              description: With its extension; what the recipient sees.
            caption:
              type: string
              minLength: 1
              maxLength: 1024
          required:
            - phone_number_id
            - contact
            - type
            - url
            - filename
        - type: object
          properties:
            phone_number_id:
              type: string
              minLength: 1
              description: >-
                The WhatsApp number to send from. `GET /whatsapp/senders` lists
                them.
            contact:
              anyOf:
                - type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                      pattern: >-
                        ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  required:
                    - id
                - type: object
                  properties:
                    email:
                      type: string
                      format: email
                      pattern: >-
                        ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                  required:
                    - email
                - type: object
                  properties:
                    phone_number:
                      type: string
                  required:
                    - phone_number
              description: >-
                Who receives it, by id, email or phone number. An unknown phone
                number creates the contact; an id or email must be an existing
                contact that has a phone number.
            reference_id:
              description: >-
                Your own id for this message (an order id). Stored and echoed
                back.
              type: string
              minLength: 1
              maxLength: 255
            idempotency_key:
              description: >-
                Send the same key on a retry and the first result comes back
                without a second message going out. Keys are permanent per
                organization and the body is not compared, so key on the message
                (order id + event), not on the order. A key whose send WhatsApp
                refused is released; one whose outcome is unknown stays taken.
              type: string
              minLength: 1
              maxLength: 255
            type:
              type: string
              const: location
            latitude:
              type: number
              minimum: -90
              maximum: 90
            longitude:
              type: number
              minimum: -180
              maximum: 180
            name:
              type: string
              minLength: 1
              maxLength: 1000
            address:
              type: string
              minLength: 1
              maxLength: 1000
          required:
            - phone_number_id
            - contact
            - type
            - latitude
            - longitude
        - type: object
          properties:
            phone_number_id:
              type: string
              minLength: 1
              description: >-
                The WhatsApp number to send from. `GET /whatsapp/senders` lists
                them.
            contact:
              anyOf:
                - type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                      pattern: >-
                        ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  required:
                    - id
                - type: object
                  properties:
                    email:
                      type: string
                      format: email
                      pattern: >-
                        ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                  required:
                    - email
                - type: object
                  properties:
                    phone_number:
                      type: string
                  required:
                    - phone_number
              description: >-
                Who receives it, by id, email or phone number. An unknown phone
                number creates the contact; an id or email must be an existing
                contact that has a phone number.
            reference_id:
              description: >-
                Your own id for this message (an order id). Stored and echoed
                back.
              type: string
              minLength: 1
              maxLength: 255
            idempotency_key:
              description: >-
                Send the same key on a retry and the first result comes back
                without a second message going out. Keys are permanent per
                organization and the body is not compared, so key on the message
                (order id + event), not on the order. A key whose send WhatsApp
                refused is released; one whose outcome is unknown stays taken.
              type: string
              minLength: 1
              maxLength: 255
            type:
              type: string
              const: location_request
            text:
              type: string
              minLength: 1
              maxLength: 1024
              description: Shown above the "Send location" button.
          required:
            - phone_number_id
            - contact
            - type
            - text
        - type: object
          properties:
            phone_number_id:
              type: string
              minLength: 1
              description: >-
                The WhatsApp number to send from. `GET /whatsapp/senders` lists
                them.
            contact:
              anyOf:
                - type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                      pattern: >-
                        ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  required:
                    - id
                - type: object
                  properties:
                    email:
                      type: string
                      format: email
                      pattern: >-
                        ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                  required:
                    - email
                - type: object
                  properties:
                    phone_number:
                      type: string
                  required:
                    - phone_number
              description: >-
                Who receives it, by id, email or phone number. An unknown phone
                number creates the contact; an id or email must be an existing
                contact that has a phone number.
            reference_id:
              description: >-
                Your own id for this message (an order id). Stored and echoed
                back.
              type: string
              minLength: 1
              maxLength: 255
            idempotency_key:
              description: >-
                Send the same key on a retry and the first result comes back
                without a second message going out. Keys are permanent per
                organization and the body is not compared, so key on the message
                (order id + event), not on the order. A key whose send WhatsApp
                refused is released; one whose outcome is unknown stays taken.
              type: string
              minLength: 1
              maxLength: 255
            type:
              type: string
              const: buttons
            text:
              type: string
              minLength: 1
              maxLength: 1024
            header:
              type: string
              minLength: 1
              maxLength: 60
            footer:
              type: string
              minLength: 1
              maxLength: 60
            buttons:
              minItems: 1
              maxItems: 3
              type: array
              items:
                $ref: '#/components/schemas/WhatsAppApiReplyButtonDto'
          required:
            - phone_number_id
            - contact
            - type
            - text
            - buttons
        - type: object
          properties:
            phone_number_id:
              type: string
              minLength: 1
              description: >-
                The WhatsApp number to send from. `GET /whatsapp/senders` lists
                them.
            contact:
              anyOf:
                - type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                      pattern: >-
                        ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  required:
                    - id
                - type: object
                  properties:
                    email:
                      type: string
                      format: email
                      pattern: >-
                        ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                  required:
                    - email
                - type: object
                  properties:
                    phone_number:
                      type: string
                  required:
                    - phone_number
              description: >-
                Who receives it, by id, email or phone number. An unknown phone
                number creates the contact; an id or email must be an existing
                contact that has a phone number.
            reference_id:
              description: >-
                Your own id for this message (an order id). Stored and echoed
                back.
              type: string
              minLength: 1
              maxLength: 255
            idempotency_key:
              description: >-
                Send the same key on a retry and the first result comes back
                without a second message going out. Keys are permanent per
                organization and the body is not compared, so key on the message
                (order id + event), not on the order. A key whose send WhatsApp
                refused is released; one whose outcome is unknown stays taken.
              type: string
              minLength: 1
              maxLength: 255
            type:
              type: string
              const: list
            text:
              type: string
              minLength: 1
              maxLength: 1024
            header:
              type: string
              minLength: 1
              maxLength: 60
            footer:
              type: string
              minLength: 1
              maxLength: 60
            button:
              type: string
              minLength: 1
              maxLength: 20
              description: Label of the button that opens the list.
            sections:
              minItems: 1
              maxItems: 10
              type: array
              items:
                $ref: '#/components/schemas/WhatsAppApiListSectionDto'
              description: At most 10 rows in total across all sections.
          required:
            - phone_number_id
            - contact
            - type
            - text
            - button
            - sections
        - type: object
          properties:
            phone_number_id:
              type: string
              minLength: 1
              description: >-
                The WhatsApp number to send from. `GET /whatsapp/senders` lists
                them.
            contact:
              anyOf:
                - type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                      pattern: >-
                        ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  required:
                    - id
                - type: object
                  properties:
                    email:
                      type: string
                      format: email
                      pattern: >-
                        ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                  required:
                    - email
                - type: object
                  properties:
                    phone_number:
                      type: string
                  required:
                    - phone_number
              description: >-
                Who receives it, by id, email or phone number. An unknown phone
                number creates the contact; an id or email must be an existing
                contact that has a phone number.
            reference_id:
              description: >-
                Your own id for this message (an order id). Stored and echoed
                back.
              type: string
              minLength: 1
              maxLength: 255
            idempotency_key:
              description: >-
                Send the same key on a retry and the first result comes back
                without a second message going out. Keys are permanent per
                organization and the body is not compared, so key on the message
                (order id + event), not on the order. A key whose send WhatsApp
                refused is released; one whose outcome is unknown stays taken.
              type: string
              minLength: 1
              maxLength: 255
            type:
              type: string
              const: link_button
            text:
              type: string
              minLength: 1
              maxLength: 1024
            header:
              type: string
              minLength: 1
              maxLength: 60
            footer:
              type: string
              minLength: 1
              maxLength: 60
            display_text:
              type: string
              minLength: 1
              maxLength: 20
            url:
              type: string
              format: uri
          required:
            - phone_number_id
            - contact
            - type
            - text
            - display_text
            - url
    SendWhatsappMessageOutputDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/SendWhatsappMessageOutputDto'
      oneOf:
        - type: object
          properties:
            id:
              type: string
              format: uuid
              pattern: >-
                ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
              description: Our id for this send.
            whatsapp_message_id:
              type: string
            reference_id:
              type:
                - string
                - 'null'
            delivery:
              type: string
              const: session
              description: The message is on a session timeline now.
            opencx_session_id:
              type: string
              format: uuid
              pattern: >-
                ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            opencx_message_id:
              type: string
              format: uuid
              pattern: >-
                ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
          required:
            - id
            - whatsapp_message_id
            - reference_id
            - delivery
            - opencx_session_id
            - opencx_message_id
          additionalProperties: false
        - type: object
          properties:
            id:
              type: string
              format: uuid
              pattern: >-
                ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
              description: Our id for this send.
            whatsapp_message_id:
              type: string
            reference_id:
              type:
                - string
                - 'null'
            delivery:
              type: string
              const: hidden
              description: >-
                No session was opened; the customer's reply will open one
                carrying this message.
            opencx_session_id:
              type: 'null'
            opencx_message_id:
              type: 'null'
          required:
            - id
            - whatsapp_message_id
            - reference_id
            - delivery
            - opencx_session_id
            - opencx_message_id
          additionalProperties: false
    ErrorDto:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
    WhatsAppTemplateWhenSessionOpen:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/WhatsAppTemplateWhenSessionOpenInput'
      type: string
      enum:
        - append
        - hidden
    WhatsAppApiReplyButtonDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/WhatsAppApiReplyButtonDtoInput'
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 256
          description: Comes back as the reply payload when tapped.
        title:
          type: string
          minLength: 1
          maxLength: 20
      required:
        - id
        - title
    WhatsAppApiListSectionDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/WhatsAppApiListSectionDtoInput'
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 24
        rows:
          minItems: 1
          maxItems: 10
          type: array
          items:
            $ref: '#/components/schemas/WhatsAppApiListRowDto'
      required:
        - title
        - rows
    WhatsAppApiListRowDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/WhatsAppApiListRowDtoInput'
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 200
          description: Comes back as the reply payload when picked.
        title:
          type: string
          minLength: 1
          maxLength: 24
        description:
          type: string
          minLength: 1
          maxLength: 72
      required:
        - id
        - title
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.