Integração de API: Enviar e Programar Mensagens a partir de Outro Sistema

Envie e programe mensagens do WhatsApp a partir de sistemas externos. Guia técnica da API da Vambe para envios imediatos, Smart Templates com IA e agendamento.

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.

⚠️ 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.

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
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]

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

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

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

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

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

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"
}'

AnteriorReativação Inteligente para Agendamentos PróximoComo criar mensagens de reativação?

Atualizado há 5 meses

Isto foi útil?