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

# Send Template to Customer

> Sends an approved template to one customer.

Put the customer's ID in the URL, then send the template details in the request.

For example, to send to customer `5`, use `/api/v1/contacts/5/messages`.


## OpenAPI

````yaml /api-collection/chatflows-api-v1.json post /api/v1/contacts/{contact_id}/messages
openapi: 3.1.0
info:
  title: ChatFlows REST API
  version: 1.0.0
  description: >-
    ChatFlows REST API (v1).


    **Base URL:** `https://app.chatflows.io/api/v1` — also shown, with a copy
    button, on your **Developer API Keys** page.


    **Auth:** every authenticated request sends `Authorization: Bearer <token>`,
    where the token is created under **Setup → Developer API Keys** in your
    dashboard.


    **What a token can see:** a token belongs to ONE workspace — your store's.
    Every endpoint returns only that workspace's data, and `/api/v1/account`
    describes your own workspace. A token created before tokens were tied to a
    workspace is refused with `401 token_not_scoped`; create a new one to
    replace it.


    **Scopes:** each endpoint's description lists the token ability it requires.
    Create your token with the matching scopes.


    **Pagination:** list endpoints return `{ data, links: { next, prev }, meta
    }`. Large/append-only collections (contacts, group members, webhooks) use
    opaque cursor pagination — follow `links.next` until it is `null`.
    `per_page` is clamped to 5–100.


    **Async sends:** message and OTP sends return `202` and are processed on the
    queue.


    **Error envelope:**

    ```json

    { "message": "...", "error_code": "...", "status": 4xx }

    ```


    **Modules:** Auth/Account · Channels · Contacts · Statuses · Sources ·
    Groups · Labels · Templates · Messages · Conversations · OTP.
servers:
  - url: https://app.chatflows.io
    description: ChatFlows
security:
  - bearerAuth: []
tags:
  - name: Root
    description: Unauthenticated service metadata.
  - name: Auth & Account
    description: Verify your token, and read workspace identity, plan and usage.
  - name: Channels
    description: Connected WhatsApp accounts and their phone numbers.
  - name: Customers
    description: Create, read, update, merge and bulk-manage customers.
  - name: Customer Statuses
    description: The pipeline statuses a contact can be assigned.
  - name: Customer Sources
    description: Where a contact originated (e.g. website, referral).
  - name: Customer Groups
    description: Named groups used to segment contacts and target campaigns.
  - name: Customer Labels
    description: Free-form labels for tagging contacts.
  - name: Templates
    description: WhatsApp message templates and their Meta approval status.
  - name: Messages
    description: Send template and free-form messages, and read delivery status.
  - name: Conversations
    description: Customer conversation threads and their message history.
  - name: OTP
    description: Send, verify and resend one-time passcodes over WhatsApp.
  - name: Error Examples
    description: Reference shapes for the errors any endpoint may return.
paths:
  /api/v1/contacts/{contact_id}/messages:
    post:
      tags:
        - Messages
      summary: Send Template to Customer
      operationId: messagesSendTemplateToContactConvenience
      parameters:
        - name: contact_id
          in: path
          required: true
          schema:
            type: integer
            example: 1
          description: The customer's `id`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                channel_id:
                  type: integer
                  description: >-
                    The ID of the WhatsApp number you send from. Find it under
                    `endpoints` in List Channels.
                template_id:
                  type: integer
                  description: The template's `id`. The template must be approved.
                template_data:
                  type: object
                  properties:
                    components:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                          parameters:
                            type: array
                            items:
                              type: object
                              properties:
                                type:
                                  type: string
                                text:
                                  type: string
                  description: Values for the template's variables, if it has any.
                idempotency_key:
                  type:
                    - string
                    - 'null'
                  maxLength: 64
                  description: >-
                    Optional. A unique value of your own. If you send the same
                    request twice with the same key, the message is only sent
                    once.
            examples:
              Send Template to Contact (convenience):
                summary: Send Template to Contact (convenience)
                value:
                  channel_id: 2
                  template_id: 1
                  template_data:
                    components:
                      - type: body
                        parameters:
                          - type: text
                            text: '#A123'
      responses:
        '202':
          description: 202 Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                      conversation_id:
                        type: integer
                      contact_id:
                        type: integer
                      channel_id:
                        type: integer
                      type:
                        type: string
                      status:
                        type: string
                      body: {}
                      metadata: {}
                      error_message: {}
                      error_details: {}
                      sent_at: {}
                      delivered_at: {}
                      read_at: {}
                      created_at:
                        type: string
              examples:
                202 Accepted:
                  summary: 202 Accepted
                  value:
                    status: queued
                    data:
                      id: 88
                      conversation_id: 12
                      contact_id: 1
                      channel_id: 2
                      type: template
                      status: queued
                      body: null
                      metadata: null
                      error_message: null
                      error_details: null
                      sent_at: null
                      delivered_at: null
                      read_at: null
                      created_at: '2026-06-26T10:00:00+00:00'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          description: 422 No Phone
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  error_code:
                    type: string
                  status:
                    type: integer
              examples:
                422 No Phone:
                  summary: 422 No Phone
                  value:
                    message: Contact has no phone number.
                    error_code: no_phone
                    status: 422
                422 Contact Opted Out:
                  summary: 422 Contact Opted Out
                  value:
                    message: Contact has opted out of marketing messages.
                    error_code: contact_opted_out
                    status: 422
        '429':
          description: 429 Send Rate Limited
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  error_code:
                    type: string
                  status:
                    type: integer
              examples:
                429 Send Rate Limited:
                  summary: 429 Send Rate Limited
                  value:
                    message: >-
                      Send rate limit reached for this WhatsApp number. Please
                      retry shortly.
                    error_code: send_rate_limited
                    status: 429
      security:
        - bearerAuth:
            - messages:send
components:
  responses:
    Unauthorized:
      description: >-
        Missing, invalid or expired API token — or an older token that is not
        tied to a workspace (`token_not_scoped`), in which case create a new one
        on the Developer API Keys page.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Missing API token.
            error_code: unauthenticated
            status: 401
    PaymentRequired:
      description: >-
        Your workspace has no active subscription, or its first payment is still
        pending.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Subscription required or expired.
            error_code: subscription_required
            status: 402
    Forbidden:
      description: >-
        The token lacks the required scope, or the account is suspended or on
        hold.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: 'This token is missing the required scope: contacts:write.'
            error_code: insufficient_scope
            status: 403
  schemas:
    Error:
      type: object
      description: Standard error envelope returned by every endpoint.
      properties:
        message:
          type: string
          description: Human-readable explanation.
        error_code:
          type: string
          description: Stable machine-readable code — branch on this, not the message.
        status:
          type: integer
          description: HTTP status code.
      required:
        - message
        - error_code
        - status
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your API key. Create one under **Setup → Developer API Keys** and select
        the permissions this endpoint needs.

````

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