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

# Send a WhatsApp template

> Sends one approved WhatsApp template to one phone number. If the recipient has no WhatsApp conversation yet, a contact and conversation are created and the send opens the conversation (business-initiated). The sent template is recorded on the conversation timeline like any other outbound message.

Rate limit: 60 requests per minute.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/whatsapp/messages
openapi: 3.1.0
info:
  title: Adraa Inbox API
  description: >-
    Public REST API for Adraa Inbox. Assign agents to conversations and send
    messages from your own systems. Authenticate every request with a workspace
    API token.
  version: 1.0.0
  contact:
    email: support@adraa.ai
servers:
  - url: https://api.inbox.adraa.ai
    description: Production
security:
  - apiToken: []
paths:
  /api/v1/whatsapp/messages:
    post:
      summary: Send a WhatsApp template
      description: >-
        Sends one approved WhatsApp template to one phone number. If the
        recipient has no WhatsApp conversation yet, a contact and conversation
        are created and the send opens the conversation (business-initiated).
        The sent template is recorded on the conversation timeline like any
        other outbound message.


        Rate limit: 60 requests per minute.
      operationId: sendWhatsappTemplate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - to
                - templateName
              properties:
                to:
                  type: string
                  maxLength: 32
                  description: Recipient phone number in international format.
                  example: '+15551234567'
                templateName:
                  type: string
                  maxLength: 512
                  description: Name of an approved WhatsApp template in this workspace.
                  example: order_status_update
                language:
                  type: string
                  default: en_US
                  description: Template language code.
                  example: en_US
                parameters:
                  type: array
                  items:
                    type: string
                    maxLength: 1024
                  description: >-
                    Values for the template's {{1}}, {{2}}, … placeholders, in
                    order.
                  example:
                    - Sara
                    - A-1043
                    - Shipped
                headerImageUrl:
                  type: string
                  format: uri
                  maxLength: 2048
                  description: >-
                    Public image URL for a template that has a media (image)
                    header.
                from:
                  type: string
                  maxLength: 64
                  description: >-
                    Which connected WhatsApp number sends: an account id or
                    phone number. Optional when exactly one number is connected;
                    required (as a disambiguator) when several are.
                  example: '+15559876543'
                name:
                  type: string
                  maxLength: 120
                  description: >-
                    Display name applied only when this send creates the
                    contact.
                  example: Sara Ahmed
      responses:
        '201':
          description: Template sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  conversationId:
                    type: string
                    description: The WhatsApp conversation the template was sent on.
                  created:
                    type: boolean
                    description: True when this send created a new contact/conversation.
                  message:
                    $ref: '#/components/schemas/Message'
        '400':
          description: >-
            No connected number, an ambiguous or unknown `from`, a missing
            recipient phone, or a Meta send error (e.g. the template is not
            approved)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: WHATSAPP_SENDER_AMBIGUOUS
                  message: Multiple WhatsApp numbers are connected; specify "from"
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Message:
      type: object
      properties:
        id:
          type: string
          description: Message ID.
          example: cmbxh2k3a0001ph01q8r9s0t1
        conversationId:
          type: string
          example: cmbxgz9pq0003ph01m4n5o6p7
        senderId:
          type: string
          description: >-
            Sender identifier. Messages sent through the API use
            `api:<tokenId>`.
          example: api:cmbxh1k3a0001ph01e6f7g8h9
        senderType:
          type: string
          example: agent
        body:
          type: string
          example: Hi! Your order has shipped and should arrive on Friday.
        replyToMessageId:
          type:
            - string
            - 'null'
          example: null
        replyQuote:
          type:
            - object
            - 'null'
          example: null
        metadata:
          type:
            - object
            - 'null'
          description: >-
            Channel delivery metadata. For email conversations this includes the
            From/To addresses and SES message ID.
          example: null
        status:
          type: string
          enum:
            - sent
            - delivered
            - read
            - failed
            - deleted
          description: >-
            Delivery status. `failed` means the message was stored but could not
            be delivered on the conversation's channel (for example, the
            workspace has no verified email domain).
          example: sent
        createdAt:
          type: string
          format: date-time
          example: '2026-06-12T10:30:00.000Z'
        attachments:
          type: array
          description: >-
            Always empty for API-sent messages; attachments are not yet
            supported.
          items:
            type: object
          example: []
        sender:
          type: object
          description: >-
            How the sender is displayed in the conversation. API-sent messages
            show as "API".
          properties:
            id:
              type: string
              example: api:cmbxh1k3a0001ph01e6f7g8h9
            nickname:
              type: string
              example: API
            company:
              type: string
              example: acme
            role:
              type: string
              example: automation
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code.
            message:
              type: string
              description: Human-readable explanation.
            details:
              description: Field-level details for validation errors.
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string
  responses:
    Unauthorized:
      description: Missing, invalid, or revoked API token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INVALID_API_TOKEN
              message: Invalid or revoked API token
  securitySchemes:
    apiToken:
      type: http
      scheme: bearer
      description: >-
        Workspace API token created in Settings → API. Tokens start with
        `adraa_`.

````