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

# Send WhatsApp Template

> Send an approved WhatsApp message template to a contact

Sends a pre-approved WhatsApp Business message template to a contact. Templates must be approved by Meta before use. Use [Get WhatsApp Templates](/api-reference/endpoint/waba-get-templates) to list available templates.

<Note>
  WhatsApp requires using templates to initiate conversations that have been inactive for more than 24 hours. Free-form messages can only be sent within an active 24-hour window.
</Note>

## Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication.
</ParamField>

## Body

<ParamField body="channel_id" type="string" required>
  UUID of the WABA channel to send from.
</ParamField>

<ParamField body="contact_id" type="string" required>
  UUID of the contact to message.
</ParamField>

<ParamField body="template_name" type="string" required>
  Name of the approved WhatsApp template (e.g. `primer_contacto_v1`).
</ParamField>

<ParamField body="language_code" type="string" default="es">
  Language code for the template (e.g. `es`, `en_US`). Defaults to `es`.
</ParamField>

<ParamField body="components" type="array">
  Template variable substitutions. Structure follows the Meta Cloud API format.

  <Expandable title="Component object">
    <ParamField body="type" type="string" required>
      Component type: `BODY`, `HEADER`, or `BUTTON`.
    </ParamField>

    <ParamField body="parameters" type="array">
      Array of parameter objects to fill template variables.

      <Expandable title="Parameter object">
        <ParamField body="type" type="string" required>
          Parameter type: `text`, `image`, `document`, etc.
        </ParamField>

        <ParamField body="text" type="string">
          Text value for `text` type parameters.
        </ParamField>

        <ParamField body="parameter_name" type="string">
          The variable name in the template (e.g. `nombre`).
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="thread_id" type="string">
  UUID of an existing thread. If provided, `channel_id` and `contact_id` are inferred automatically.
</ParamField>

<ParamField body="save_message" type="boolean" default="true">
  Whether to save the message in the conversation thread. Defaults to `true`.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  `true` if the template was sent successfully.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="Response data">
    <ResponseField name="message_id" type="string">
      Internal UUID of the message record.
    </ResponseField>

    <ResponseField name="provider_id" type="string">
      WhatsApp message ID returned by Meta.
    </ResponseField>

    <ResponseField name="thread_id" type="string">
      UUID of the conversation thread.
    </ResponseField>
  </Expandable>
</ResponseField>

## Error Codes

* `400 Bad Request` — Missing fields, invalid channel, or template not found
* `401 Unauthorized` — Invalid or missing API key
* `404 Not Found` — Contact not found
* `500 Internal Server Error` — Meta API error or internal failure

## Code Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.contactship.ai/v1/waba/send-template" \
    -H "x-api-key: your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "channel_id": "chn_abc123",
      "contact_id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "template_name": "primer_contacto_v1",
      "language_code": "es",
      "components": [
        {
          "type": "BODY",
          "parameters": [
            { "type": "text", "parameter_name": "nombre", "text": "Juan Pérez" },
            { "type": "text", "parameter_name": "fecha", "text": "ayer" }
          ]
        }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.contactship.ai/v1/waba/send-template',
    {
      method: 'POST',
      headers: {
        'x-api-key': 'your-api-key',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        channel_id: 'chn_abc123',
        contact_id: 'c1d2e3f4-a5b6-7890-cdef-123456789012',
        template_name: 'primer_contacto_v1',
        language_code: 'es',
        components: [
          {
            type: 'BODY',
            parameters: [
              { type: 'text', parameter_name: 'nombre', text: 'Juan Pérez' },
              { type: 'text', parameter_name: 'fecha', text: 'ayer' },
            ],
          },
        ],
      }),
    }
  );
  const result = await response.json();
  console.log(result.data.thread_id);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.contactship.ai/v1/waba/send-template',
      headers={'x-api-key': 'your-api-key'},
      json={
          'channel_id': 'chn_abc123',
          'contact_id': 'c1d2e3f4-a5b6-7890-cdef-123456789012',
          'template_name': 'primer_contacto_v1',
          'language_code': 'es',
          'components': [
              {
                  'type': 'BODY',
                  'parameters': [
                      {'type': 'text', 'parameter_name': 'nombre', 'text': 'Juan Pérez'},
                      {'type': 'text', 'parameter_name': 'fecha', 'text': 'ayer'},
                  ],
              }
          ],
      },
  )
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json Example Response theme={null}
  {
    "success": true,
    "message": "Plantilla enviada y guardada",
    "data": {
      "message_id": "msg-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "provider_id": "wamid.HBgNMTIxMjM0NTY3ODkwFQIAERgSM...",
      "thread_id": "thr-b2c3d4e5-f6a7-8901-bcde-f12345678901"
    }
  }
  ```
</ResponseExample>