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

# Enviar mensagem

> Enviar mensagens individuais de template do WhatsApp Business

## Descrição

Este endpoint permite enviar um template do WhatsApp para um destinatário individual. Implementa um padrão **fire-and-forget**: ao enviar a mensagem, retorna um `message_id` (wamid da Meta) que você pode usar para verificar o status da mensagem.

A API valida o template, resolve as variáveis e envia a mensagem pela API da Meta de forma síncrona.

## Header de autenticação

<ParamField header="X-API-Key" type="string" required>
  Sua API Key da Mindo. Formato: `mindo_xxxxxxxxxxxxxxxxxxxxxxxx`
</ParamField>

## Parâmetros do body

<ParamField body="phone_number_id" type="string" required>
  ID do número de telefone do WhatsApp na Meta a partir do qual a mensagem será enviada. Você pode obtê-lo no endpoint [Obter contas de negócio](/pt/api-reference/cuentas-negocio/obtener-cuentas).
</ParamField>

<ParamField body="template_name" type="string" required>
  Nome do template aprovado a ser enviado. Deve ter status `APPROVED` na Meta.
</ParamField>

<ParamField body="language" type="string">
  Idioma do template. Padrão: `"es"`. Exemplos: `"es"`, `"en"`, `"pt_BR"`.
</ParamField>

<ParamField body="recipient_phone" type="string" required>
  Número de telefone do destinatário em formato internacional (ex.: `"+5491112345678"`). Sem espaços.
</ParamField>

<ParamField body="variables" type="object">
  Variáveis personalizadas para o template. As chaves devem corresponder às variáveis definidas no template.
</ParamField>

<ParamField body="button_variables" type="object">
  Variáveis para botões dinâmicos do template. As chaves usam o formato `button_0`, `button_1`, etc., onde o número corresponde ao índice do botão (começando em 0). Os valores são os sufixos dinâmicos ou payloads de cada botão.

  **Importante:** Botões do tipo URL suportam apenas 1 variável.
</ParamField>

## Resposta (200 OK)

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

<ResponseField name="message_id" type="string">
  ID da mensagem atribuído pela Meta (wamid). Use para verificar o status da mensagem.
</ResponseField>

<ResponseField name="template_name" type="string">
  Nome do template enviado.
</ResponseField>

<ResponseField name="recipient_phone" type="string">
  Número de telefone do destinatário.
</ResponseField>

<ResponseField name="status" type="string">
  Status inicial da mensagem. Sempre `"sent"` quando enviada com sucesso.
</ResponseField>

<ResponseField name="sent_at" type="string (ISO 8601)">
  Data e hora do envio da mensagem.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.mindosoftware.com/api/v1/meta-templates/send/ \
    -H "X-API-Key: mindo_xxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "phone_number_id": "813497231850626",
      "template_name": "welcome_message",
      "language": "es",
      "recipient_phone": "+5491112345678",
      "variables": {
        "name": "Juan Perez",
        "code": "ABC123"
      },
      "button_variables": {
        "button_0": "ABC-123"
      }
    }'
  ```

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

  response = requests.post(
      "https://api.mindosoftware.com/api/v1/meta-templates/send/",
      headers={"X-API-Key": "mindo_xxxxxxxxxxxxxxxxxxxxxxxx"},
      json={
          "phone_number_id": "813497231850626",
          "template_name": "welcome_message",
          "language": "es",
          "recipient_phone": "+5491112345678",
          "variables": {
              "name": "Juan Perez",
              "code": "ABC123"
          },
          "button_variables": {
              "button_0": "ABC-123"
          }
      }
  )

  data = response.json()
  print(f"Message ID: {data['message_id']}")
  print(f"Status: {data['status']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.mindosoftware.com/api/v1/meta-templates/send/",
    {
      method: "POST",
      headers: {
        "X-API-Key": "mindo_xxxxxxxxxxxxxxxxxxxxxxxx",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        phone_number_id: "813497231850626",
        template_name: "welcome_message",
        language: "es",
        recipient_phone: "+5491112345678",
        variables: {
          name: "Juan Perez",
          code: "ABC123"
        },
        button_variables: {
          button_0: "ABC-123"
        }
      })
    }
  );

  const data = await response.json();
  console.log("Message ID:", data.message_id);
  console.log("Status:", data.status);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - OK theme={null}
  {
    "success": true,
    "message_id": "wamid.HBgNNTQ5MTEyMzQ1Njc4FQIAERgSQjVBN0YzRjQ2NzFCNDVBNQA=",
    "template_name": "welcome_message",
    "recipient_phone": "+5491112345678",
    "status": "sent",
    "sent_at": "2025-11-16T21:30:00Z"
  }
  ```

  ```json 400 - Validação theme={null}
  {
    "phone_number_id": ["This field is required."],
    "recipient_phone": ["This field is required."]
  }
  ```

  ```json 400 - Template não aprovado theme={null}
  {
    "error": "Template 'welcome_message' no tiene estado APPROVED"
  }
  ```

  ```json 404 - Template não encontrado theme={null}
  {
    "error": "Template 'welcome_message' (language: es) no encontrado en este business account"
  }
  ```

  ```json 404 - Número não encontrado theme={null}
  {
    "error": "Numero de WhatsApp con ID '813497231850626' no encontrado"
  }
  ```

  ```json 401 - Não autenticado theme={null}
  {
    "error": "Este endpoint requiere autenticacion con API Key (header X-API-Key)"
  }
  ```
</ResponseExample>

## Status das mensagens

O campo `status` da mensagem pode ter os seguintes valores:

| Status      | Descrição                                        |
| ----------- | ------------------------------------------------ |
| `sent`      | Mensagem enviada para a Meta com sucesso         |
| `delivered` | Mensagem entregue no dispositivo do destinatário |
| `read`      | Mensagem lida pelo destinatário                  |
| `failed`    | Falha no envio da mensagem                       |

<Note>
  O endpoint de consulta individual de status (`GET /api/v1/meta-templates/messages/\{message_id\}/`) estará disponível em breve. Enquanto isso, você pode usar o `message_id` retornado para rastreabilidade interna.
</Note>

## Casos de uso

<AccordionGroup>
  <Accordion title="Mensagem de boas-vindas para novo cliente">
    Envie uma mensagem de boas-vindas personalizada quando um novo cliente se cadastrar.

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

    response = requests.post(
        "https://api.mindosoftware.com/api/v1/meta-templates/send/",
        headers={"X-API-Key": "mindo_xxxxxxxxxxxxxxxxxxxxxxxx"},
        json={
            "phone_number_id": "813497231850626",
            "template_name": "welcome_message",
            "recipient_phone": "+5491112345678",
            "variables": {
                "name": "Juan Perez"
            }
        }
    )

    data = response.json()
    print(f"Boas-vindas enviadas: {data['message_id']}")
    ```

    ```javascript JavaScript theme={null}
    const response = await fetch(
      "https://api.mindosoftware.com/api/v1/meta-templates/send/",
      {
        method: "POST",
        headers: {
          "X-API-Key": "mindo_xxxxxxxxxxxxxxxxxxxxxxxx",
          "Content-Type": "application/json"
        },
        body: JSON.stringify({
          phone_number_id: "813497231850626",
          template_name: "welcome_message",
          recipient_phone: "+5491112345678",
          variables: { name: "Juan Perez" }
        })
      }
    );

    const data = await response.json();
    console.log("Boas-vindas enviadas:", data.message_id);
    ```
  </Accordion>

  <Accordion title="Código de verificação">
    Envie um código de verificação único para um usuário.

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

    code = secrets.token_hex(3).upper()

    response = requests.post(
        "https://api.mindosoftware.com/api/v1/meta-templates/send/",
        headers={"X-API-Key": "mindo_xxxxxxxxxxxxxxxxxxxxxxxx"},
        json={
            "phone_number_id": "813497231850626",
            "template_name": "verification_code",
            "recipient_phone": "+5491112345678",
            "variables": {
                "name": "Juan",
                "code": code
            }
        }
    )

    data = response.json()
    print(f"Código {code} enviado: {data['message_id']}")
    ```

    ```javascript JavaScript theme={null}
    const code = Math.random().toString(36).substring(2, 8).toUpperCase();

    const response = await fetch(
      "https://api.mindosoftware.com/api/v1/meta-templates/send/",
      {
        method: "POST",
        headers: {
          "X-API-Key": "mindo_xxxxxxxxxxxxxxxxxxxxxxxx",
          "Content-Type": "application/json"
        },
        body: JSON.stringify({
          phone_number_id: "813497231850626",
          template_name: "verification_code",
          recipient_phone: "+5491112345678",
          variables: { name: "Juan", code }
        })
      }
    );

    const data = await response.json();
    console.log(`Código ${code} enviado:`, data.message_id);
    ```
  </Accordion>

  <Accordion title="Notificação de status do pedido">
    Notifique um cliente quando o status do pedido mudar.

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

    response = requests.post(
        "https://api.mindosoftware.com/api/v1/meta-templates/send/",
        headers={"X-API-Key": "mindo_xxxxxxxxxxxxxxxxxxxxxxxx"},
        json={
            "phone_number_id": "813497231850626",
            "template_name": "order_update",
            "recipient_phone": "+5491112345678",
            "variables": {
                "order_id": "ORD-001",
                "status": "Em trânsito"
            }
        }
    )

    data = response.json()
    print(f"Notificação enviada: {data['message_id']}")
    ```

    ```javascript JavaScript theme={null}
    const response = await fetch(
      "https://api.mindosoftware.com/api/v1/meta-templates/send/",
      {
        method: "POST",
        headers: {
          "X-API-Key": "mindo_xxxxxxxxxxxxxxxxxxxxxxxx",
          "Content-Type": "application/json"
        },
        body: JSON.stringify({
          phone_number_id: "813497231850626",
          template_name: "order_update",
          recipient_phone: "+5491112345678",
          variables: { order_id: "ORD-001", status: "Em trânsito" }
        })
      }
    );

    const data = await response.json();
    console.log("Notificação enviada:", data.message_id);
    ```
  </Accordion>
</AccordionGroup>