> For the complete documentation index, see [llms.txt](https://academy.vambe.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.vambe.ai/seguimiento-de-clientes/seguimiento-de-clientes-pt-br/integracoes/integracao-de-api-enviar-e-programar-mensagens-a-partir-de-outro-sistema.md).
# Integração de API: Enviar e Programar Mensagens a partir de Outro Sistema
A API da Vambe permite que seus sistemas externos (CRM, ERP, Web) disparem mensagens de WhatsApp de forma programática. Você pode realizar envios imediatos com controle manual, usar a IA para preencher variáveis ou deixar mensagens agendadas para o futuro.
{% hint style="warning" %}
⚠️ Aviso Técnico: Este artigo exige conhecimentos de desenvolvimento e consumo de APIs REST. Se você não for desenvolvedor, compartilhe este guia com sua equipe técnica. Para todos os casos, você vai precisar da sua x-api-key, disponível na seção de Desenvolvedores.
{% endhint %}
***
#### 1. Pré-requisitos
Antes de usar qualquer endpoint, certifique-se de atender ao seguinte:
* **API Key**: A chave de autenticação da sua conta. Você pode encontrá-la [aqui](https://www.vambeai.com/developers)
* **Modelo (Template)**: A mensagem deve ser um template aprovado. Se você não tiver um, crie-o antes de continuar. 👉 [*\[Guia: Como criar e aprovar templates de WhatsApp\]*](https://academy.vambe.ai/canal/plantillas/como-crear-plantillas)
***
#### 2. Envios Imediatos (Immediate Sending)
| **Endpoint** | **Quando usá-lo?** | **Como as variáveis são preenchidas?** |
| ------------------------ | -------------------------------------------------------------- | --------------------------------------------------------------- |
| Baseado em Código (V2) | Você tem os dados estruturados e organizados no seu sistema. | Manual: Você envia a lista exata `["João", "Pedido #10"]`. |
| Inteligente (Individual) | Você tem um texto desordenado ou um parágrafo longo. | IA: Você passa o texto para a IA e ela procura qual dado serve. |
| Inteligente (Em massa) | Você quer enviar para muitas pessoas ao mesmo tempo usando IA. | IA: Igual ao anterior, mas otimizado para volume. |
Existem três formas de enviar uma mensagem agora mesmo, dependendo do nível de controle e volume de que você precisar.
**A. Envio Manual com Variáveis (Code Based V2)**
Use este endpoint se você quiser **definir exatamente qual valor vai em cada variável**, na ordem específica do template.
* Endpoint: `Enviar Template do WhatsApp (Code Based v2)`
* 🔗 Documentação Oficial: [Clique aqui para ver a documentação](https://docs.vambe.me/reference/whatsapp-message/send-a-template-message-1)
Parâmetros Obrigatórios:
* `variables`: Lista de valores na ordem exata do template.
* `metadata`: Informações adicionais do contato.
* `phone`: Número de telefone do destinatário (To).
* `template_name`: Nome exato do template.
* `from_phone_number`: Número de origem conectado à Vambe.
**Parâmetros Opcionais:**
* `contact_name`: Para atribuir um nome ao contato na Vambe.
* `stage_id`: Define em qual etapa o cliente ou ticket aparecerá após o envio.
* `agent_id`: Atribui o ticket a um agente específico.
Lógica de Variáveis <> Template
**💡 Conceito Visual:**
Seu Template na Vambe:\
"Olá {{1}}, confirmamos sua consulta para o dia {{2}}."
Seu Código (Array de variáveis):\
"variables": \[\
"Carlos", <-- Preenche o {{1}}\
"Terça-feira 15" <-- Preenche o {{2}}\
]
**⚠️ A ordem na lista deve ser exata.**
**Exemplo de cURL**
```
curl --request POST \
--url https://api.vambe.me/v1/whatsapp/message/send-template \
--header 'Content-Type: application/json' \
--header 'x-api-key: SUA_API_KEY_AQUI' \
--data '{
"phone": "56912345678",
"template_name": "nome_exato_do_template",
"from_phone_number": "56987654321",
"variables": [
"João Pereira",
"Seu pedido #5501"
],
"metadata": {
"cliente_id": "CLI-999"
},
"stage_id": "uuid-da-etapa-destino"
}'
```
**B. Envio Inteligente: Um único destinatário (Smart Template Single)**
Neste método, o Template ID é enviado diretamente na URL do endpoint. A Inteligência Artificial utilizará as informações que você enviar no `corpo` (JSON) para preencher as variáveis do template automaticamente.
* Endpoint: `POST /api/public/whatsapp/message/send/template/{templateId}`
* 🔗 Documentação Oficial: [Referência da API aqui](https://docs.vambe.me/reference/whatsapp-message/send-a-template-message-with-unstructured-data)
**Parâmetros na URL (Query Params):**
* `x-api-key`: Sua chave de API (Obrigatório).
* `from-phone-number`: O número conectado à Vambe de onde você envia (Obrigatório).
* `stage`: ID da etapa de destino (Opcional).
**Corpo da Solicitação (Body JSON)**: Envie um objeto JSON com os dados que a IA deve processar. Se você precisar associar dados de uma integração externa, use a estrutura `integrationData`.
```
{
"contexto_chave": "valor",
"integrationData": {
"integrationContactId": "id_externo_123",
"integrationDealId": "id_do_negócio_456",
"additionalData": { "saldo": "5000" }
}
}
```
**Exemplo de Código (cURL):**
```
curl --request POST \
--url 'https://api.vambe.me/api/public/whatsapp/message/send/template/TU_TEMPLATE_ID?x-api-key=TU_API_KEY&from-phone-number=56912345678' \
--header 'Content-Type: application/json' \
--data '{
"nome": "Carlos",
"motivo": "Confirmação de consulta médica",
"integrationData": {
"integrationContactId": "crm_user_88"
}
}'
```
**C. Envio Inteligente: Em massa (Smart Template Bulk)**
Semelhante ao anterior, mas projetado para enviar para várias pessoas em uma única solicitação. O Template ID continua indo na URL, mas o body recebe um array de objetos.
* **Endpoint**: `POST /api/public/whatsapp/message/send/template/{templateId}/many`
* 🔗 **Documentação Oficial**: [Referência da API aqui](https://docs.vambe.me/reference/whatsapp-message/send-a-template-message-with-unstructured-data-1)
Parâmetros na URL (Query Params):
* `x-api-key` (Obrigatório)
* `from-phone-number` (Obrigatório)
* `stageId` (Opcional - Recomendado em vez de `stage`)
Corpo da Solicitação (Body JSON): Uma lista (array) de objetos, onde cada objeto representa os dados para um destinatário específico.
**Exemplo de Código (cURL):**
```
curl --request POST \
--url 'https://api.vambe.me/api/public/whatsapp/message/send/template/TU_TEMPLATE_ID/many?x-api-key=TU_API_KEY&from-phone-number=56912345678&stageId=uuid_etapa' \
--header 'Content-Type: application/json' \
--data '[
{
"phone": "56911111111",
"nome": "Ana",
"integrationData": { "integrationContactId": "001" }
},
{
"phone": "56922222222",
"nome": "Beto",
"integrationData": { "integrationContactId": "002" }
}
]'
```
***
#### 3. Programar Mensagens (Agendamento)
Se você precisar que a mensagem seja enviada em uma data futura, use o endpoint de criação de agendamentos.
> ⚠️ Atenção ao formato: Diferentemente dos endpoints anteriores, aqui os parâmetros do body devem usar o formato camelCase (ex: `scheduledDate`, `templateId`).
* **Endpoint**: `POST /api/public/whatsapp/message/programmed/create`
* 🔗 **Documentação Oficial**: [Referência da API aqui](https://docs.vambe.me/reference/whatsapp-message/send-a-program-a-template-message-to-send-at-a-specific-time)
**Parâmetros do Body (JSON):**
* `scheduledDate`: Data no formato ISO 8601 (ex: `2023-12-25T09:00:00Z`).
* `templateId`: ID do template.
* `contactIdentifier`: Número do destinatário.
* `channel`: `whatsapp` (API) ou `web_whatsapp` (QR).
* `isSmart`: `true` para usar IA no preenchimento das variáveis.
* `fromPhoneNumber`: Número de origem.
* `stageId`: ID da etapa de destino.
* `meta_data`: Objeto com os dados para a IA.
**Exemplo de Código (cURL):**
```
curl --request POST \
--url https://api.vambe.me/api/public/whatsapp/message/programmed/create \
--header 'Content-Type: application/json' \
--header 'x-api-key: SUA_API_KEY' \
--data '{
"scheduledDate": "2023-12-25T09:00:00Z",
"templateId": "uuid-template-id",
"contactIdentifier": "56912345678",
"channel": "whatsapp",
"isSmart": true,
"fromPhoneNumber": "56987654321",
"stageId": "uuid-etapa-id",
"meta_data": {
"nome": "Cliente de Exemplo",
"produto": "Serviço Premium"
}
}'
```
***
#### 4. Cancelar uma Mensagem Agendada
Se você precisar interromper um envio que já agendou (por exemplo, o cliente já comprou e você não quer enviar o lembrete), pode cancelá-lo via API.
* Endpoint: `Cancelar Mensagem de WhatsApp Agendada`
* 🔗 Documentação Oficial: [Clique aqui para ver a documentação](https://docs.vambe.me/reference/whatsapp-message/cancel-a-programmed-message-by-scheduled-message-id)
Requisito: Você precisa do `scheduled_message_id`. Este ID é retornado pela API na resposta (response) quando você cria o agendamento no passo anterior. Guarde-o se pretende ter a opção de cancelar.
**Exemplo de cURL**
```
curl --request POST \
--url https://api.vambe.me/v1/whatsapp/message/schedule/cancel \
--header 'Content-Type: application/json' \
--header 'x-api-key: SUA_API_KEY_AQUI' \
--data '{
"scheduled_message_id": "uuid-retornado-ao-agendar"
}'
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://academy.vambe.ai/seguimiento-de-clientes/seguimiento-de-clientes-pt-br/integracoes/integracao-de-api-enviar-e-programar-mensagens-a-partir-de-outro-sistema.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.