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

# Enviar Mensagem de Template

> Envie uma mensagem do WhatsApp usando um template aprovado

Este endpoint envia uma mensagem do WhatsApp usando um template pré-aprovado. Mensagens de template são necessárias ao iniciar uma conversa com um usuário pela primeira vez ou ao enviar mensagens fora da janela de mensagens de 24 horas.

<Note>
  Este endpoint tem limite de taxa de **5 requisições por segundo** por usuário.
</Note>

### Corpo da Requisição

<ParamField body="sender_id" type="integer" required>
  O ID do remetente WhatsApp para enviar (obtido do endpoint [Obter Remetentes](/api-reference/whatsapp/get-senders))
</ParamField>

<ParamField body="template_id" type="integer" required>
  O ID do template de mensagem a ser usado (obtido do endpoint [Obter Templates](/api-reference/whatsapp/get-templates))
</ParamField>

<ParamField body="recipient_phone" type="string" required>
  O número de telefone do destinatário em formato internacional (ex: `+1234567890`)
</ParamField>

<ParamField body="recipient_name" type="string">
  O nome do destinatário, máximo 255 caracteres (usado para rastreamento de conversa e finalidades de CRM)
</ParamField>

<ParamField body="variables" type="object">
  Pares chave-valor para variáveis do template. As chaves devem corresponder aos nomes das variáveis do template. Se o template tiver variáveis `{{1}}`, `{{2}}`, etc., forneça-as como `{"1": "valor1", "2": "valor2"}` ou usando as chaves nomeadas do array `variables` do template.

  <Expandable title="Exemplo de variáveis">
    <ParamField body="1" type="string">
      Valor para a primeira variável do template
    </ParamField>

    <ParamField body="2" type="string">
      Valor para a segunda variável do template
    </ParamField>
  </Expandable>
</ParamField>

### Campos da Resposta

<ResponseField name="success" type="boolean">
  Se a mensagem foi enviada com sucesso
</ResponseField>

<ResponseField name="conversation_id" type="integer">
  O ID da conversa (nova ou existente) associada a esta mensagem
</ResponseField>

<ResponseField name="message_id" type="integer">
  O ID do registro de mensagem da conversa
</ResponseField>

<ResponseField name="whatsapp_message_id" type="integer">
  O ID do registro da mensagem WhatsApp
</ResponseField>

<ResponseField name="message_sid" type="string">
  O SID da mensagem Twilio para rastreamento de entrega
</ResponseField>

<ResponseField name="status" type="string">
  O status inicial de entrega da mensagem (ex: `queued`, `sent`)
</ResponseField>

### Respostas de Erro

<ResponseField name="402 Saldo Insuficiente">
  <Expandable title="Resposta de Erro">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">`Saldo insuficiente. Por favor, recarregue sua conta.`</ResponseField>
    <ResponseField name="error_code" type="string">`INSUFFICIENT_BALANCE`</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="404 Não Encontrado">
  <Expandable title="Resposta de Erro">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">`Remetente não encontrado ou não pertence a você` ou `Template não encontrado ou não pertence a este remetente`</ResponseField>
    <ResponseField name="error_code" type="string">`SENDER_NOT_FOUND` ou `TEMPLATE_NOT_FOUND`</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="422 Entidade Não Processável">
  <Expandable title="Resposta de Erro">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">Mensagem de erro detalhada</ResponseField>

    <ResponseField name="error_code" type="string">
      Um de: `SENDER_OFFLINE`, `TEMPLATE_NOT_APPROVED`, `TEMPLATE_NOT_SYNCED`, `TEMPLATE_MISMATCH`, `NO_ASSISTANT_CONFIGURED`, `INVALID_PHONE`, `MESSAGING_LIMIT_UNAVAILABLE`, `VOICE_CALL_LIMIT_NOT_MET`, `TWILIO_ERROR_{code}`, `UNKNOWN_ERROR`
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://suasofia.online/api/user/whatsapp/send" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "sender_id": 12,
      "template_id": 45,
      "recipient_phone": "+1234567890",
      "recipient_name": "João Silva",
      "variables": {
        "1": "João",
        "2": "15 de janeiro, 2026",
        "3": "14:00"
      }
    }'
  ```

  ```bash Template sem variáveis theme={null}
  curl -X POST "https://suasofia.online/api/user/whatsapp/send" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "sender_id": 12,
      "template_id": 46,
      "recipient_phone": "+1234567890"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://suasofia.online/api/user/whatsapp/send',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        sender_id: 12,
        template_id: 45,
        recipient_phone: '+1234567890',
        recipient_name: 'João Silva',
        variables: {
          '1': 'João',
          '2': '15 de janeiro, 2026',
          '3': '14:00'
        }
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```

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

  response = requests.post(
      'https://suasofia.online/api/user/whatsapp/send',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'sender_id': 12,
          'template_id': 45,
          'recipient_phone': '+1234567890',
          'recipient_name': 'João Silva',
          'variables': {
              '1': 'João',
              '2': '15 de janeiro, 2026',
              '3': '14:00'
          }
      }
  )

  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Sucesso theme={null}
  {
    "success": true,
    "conversation_id": 1234,
    "message_id": 567,
    "whatsapp_message_id": 890,
    "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "queued"
  }
  ```

  ```json 402 Saldo Insuficiente theme={null}
  {
    "success": false,
    "error": "Saldo insuficiente. Por favor, recarregue sua conta.",
    "error_code": "INSUFFICIENT_BALANCE"
  }
  ```

  ```json 404 Remetente Não Encontrado theme={null}
  {
    "success": false,
    "error": "Remetente não encontrado ou não pertence a você",
    "error_code": "SENDER_NOT_FOUND"
  }
  ```

  ```json 404 Template Não Encontrado theme={null}
  {
    "success": false,
    "error": "Template não encontrado ou não pertence a este remetente",
    "error_code": "TEMPLATE_NOT_FOUND"
  }
  ```

  ```json 422 Template Não Aprovado theme={null}
  {
    "success": false,
    "error": "Template não está aprovado. Status atual: pendente",
    "error_code": "TEMPLATE_NOT_APPROVED"
  }
  ```

  ```json 422 Telefone Inválido theme={null}
  {
    "success": false,
    "error": "Formato de número de telefone inválido. Use o formato E.164 (ex: +14155551234).",
    "error_code": "INVALID_PHONE"
  }
  ```

  ```json 422 Remetente Offline theme={null}
  {
    "success": false,
    "error": "Remetente não está online. Status atual: Offline",
    "error_code": "SENDER_OFFLINE"
  }
  ```
</ResponseExample>

### Observações

* Mensagens de template devem usar templates **aprovados**. Templates com status `pendente` ou `rejeitado` falharão.
* O remetente deve estar `online`. Remetentes offline não podem enviar mensagens.
* Os custos das mensagens são automaticamente deduzidos do saldo da sua conta (créditos para usuários tenant, minutos para usuários diretos).
* Após enviar uma mensagem de template, uma janela de mensagens de 24 horas se abre. Durante esta janela, você pode enviar [mensagens livres](/api-reference/whatsapp/send-freeform) sem precisar de um template.
* Se uma conversa já existe com o destinatário, a mensagem é adicionada à conversa existente.
* Limite de taxa: 5 requisições por segundo por usuário.