API REST
A API pública integra o TWMULT a CRMs, ERPs, lojas e automações como n8n, Make e Zapier. Ela envia mensagens, gerencia contatos e campanhas e consulta pedidos.
| URL base | https://api.twmult.com/v1 |
|---|---|
| Formato | JSON (exceto o upload de mídia, em multipart/form-data) |
| Autenticação | Authorization: Bearer <chave> |
| Limite | 120 requisições por minuto por chave |
Autenticação
Crie uma chave no painel, em Conta → Integrações. A chave completa aparece uma única vez; guarde-a num local seguro. Envie-a em todas as requisições:
Authorization: Bearer twm_live_xxxxxxxxxxxxxxxxxxxxxxxx
A chave pertence a um workspace e tem acesso total a ele. Crie uma chave por sistema integrado, para poder revogar uma sem afetar as outras, e nunca a exponha em código que roda no navegador.
Nos exemplos abaixo, a chave está na variável de ambiente TWMULT_KEY:
export TWMULT_KEY="twm_live_xxxxxxxxxxxxxxxxxxxxxxxx"
Convenções
Telefones
Telefones vão só com dígitos e DDI: 5583999991234. Números brasileiros sem DDI recebem o 55 automaticamente.
Valores
Valores em dinheiro são inteiros em centavos (totalCents, valueCents): 120000 = R$ 1.200,00. Datas seguem a ISO 8601 em UTC.
Erros
Os erros seguem o formato:
{ "error": "codigo", "message": "texto" }
| Status | Quando |
|---|---|
401 | Chave ausente, inválida ou revogada. |
402 | Limite do plano atingido ou assinatura suspensa. |
404 | Recurso não encontrado. |
422 | Erro de validação. O campo issues detalha cada problema. |
429 | Mais de 120 requisições por minuto. Espere e tente de novo. |
{ "error": "plan_limit", "message": "Limite mensal de mensagens do plano atingido." }
Conexões
Listar conexões
GET/v1/instances
Lista os números de WhatsApp do workspace. Use o id em instanceId e instanceIds.
curl https://api.twmult.com/v1/instances \
-H "Authorization: Bearer $TWMULT_KEY"
[
{ "id": "clx1a2b3c", "name": "Comercial 01", "status": "CONNECTED", "phone": "5583988887777" }
]
status pode ser CONNECTED, CONNECTING ou DISCONNECTED.
Mensagens
Enviar mensagem
POST/v1/messages
| Campo | Tipo | Descrição |
|---|---|---|
phone | string | Obrigatório. Telefone do destinatário. |
text | string | Texto da mensagem. Com mídia, vira a legenda. |
instanceId | string | Opcional. Conexão que vai enviar. Padrão: a primeira conexão ativa. |
media | objeto | Opcional. type (image, video, document ou audio), url (https) ou base64, e fileName. |
curl -X POST https://api.twmult.com/v1/messages \
-H "Authorization: Bearer $TWMULT_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "5583999991234",
"text": "Seu pedido saiu para entrega 🚚"
}'
Com mídia:
curl -X POST https://api.twmult.com/v1/messages \
-H "Authorization: Bearer $TWMULT_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "5583999991234",
"text": "Segue a foto do produto",
"media": { "type": "image", "url": "https://exemplo.com/foto.jpg", "fileName": "foto.jpg" }
}'
Resposta 201:
{ "id": "clx9m8n7b", "conversationId": "clx5k4j3h", "status": "sent" }
A mensagem aparece na caixa de entrada do painel e conta no limite mensal do plano. Contatos que ainda não existem são criados.
Histórico da conversa
GET/v1/conversations/{phone}/messages?limit=50
Retorna as últimas mensagens trocadas com o telefone, em ordem cronológica. direction é IN (recebida) ou OUT (enviada).
curl "https://api.twmult.com/v1/conversations/5583999991234/messages?limit=50" \
-H "Authorization: Bearer $TWMULT_KEY"
[
{ "id": "clx9m8n7a", "direction": "IN", "type": "text", "body": "Quero comprar", "createdAt": "2026-11-16T19:58:00.000Z" },
{ "id": "clx9m8n7b", "direction": "OUT", "type": "text", "body": "Seu pedido saiu para entrega 🚚", "createdAt": "2026-11-16T20:00:00.000Z" }
]
Contatos
Listar contatos
GET/v1/contacts?phone=&tag=&page=1&pageSize=100
Filtre por phone ou pelo nome de uma etiqueta em tag. A paginação usa page (a partir de 1) e pageSize.
curl "https://api.twmult.com/v1/contacts?tag=vip&page=1&pageSize=100" \
-H "Authorization: Bearer $TWMULT_KEY"
{
"items": [
{
"id": "clx2c3d4e",
"phone": "5583999991234",
"name": "Ana",
"optOut": false,
"fields": { "cidade": "JP" },
"tags": ["vip"]
}
],
"total": 1
}
Criar ou atualizar contato
POST/v1/contacts
Cria o contato ou, se o telefone já existir, atualiza o nome, mescla os fields e adiciona as etiquetas. As etiquetas que não existem são criadas.
curl -X POST https://api.twmult.com/v1/contacts \
-H "Authorization: Bearer $TWMULT_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "5583999991234",
"name": "Ana",
"fields": { "cidade": "JP" },
"tags": ["cliente", "vip"]
}'
Resposta 201 (criado) ou 200 (atualizado), com o contato no mesmo formato da listagem.
Excluir contato
DELETE/v1/contacts/{phone}
curl -X DELETE https://api.twmult.com/v1/contacts/5583999991234 \
-H "Authorization: Bearer $TWMULT_KEY"
Resposta 204, sem corpo.
Campanhas
Listar campanhas
GET/v1/campaigns
curl https://api.twmult.com/v1/campaigns \
-H "Authorization: Bearer $TWMULT_KEY"
[
{ "id": "clx7f8g9h", "name": "Black Friday", "status": "RUNNING", "total": 1200, "sent": 430, "failed": 3 }
]
Os status possíveis estão em Campanhas.
Enviar mídia
POST/v1/media
Para usar imagem, vídeo, áudio ou documento numa campanha, envie o arquivo antes (multipart, campo file, até 16 MB) e use o id retornado como mediaId.
curl -X POST https://api.twmult.com/v1/media \
-H "Authorization: Bearer $TWMULT_KEY" \
-F "file=@promocao.jpg"
{ "id": "clx3m4e5d", "filename": "promocao.jpg", "mimeType": "image/jpeg", "size": 184320 }
Criar campanha
POST/v1/campaigns
O corpo é igual ao da criação pelo painel, mais "start": true para iniciar na hora.
| Campo | Descrição |
|---|---|
name | Nome da campanha. |
steps | Mensagens enviadas a cada contato, em ordem: { type, text, mediaId }. Tipos: text, image, video, document e audio. O texto aceita variáveis e spintax; nas mídias, é a legenda. |
instanceIds | Conexões que vão enviar, em rotação. Veja GET /v1/instances. |
audience | { all, tags, phones }: todos os contatos, os que têm alguma das etiquetas (pelo nome) e/ou uma lista de telefones. Contatos com opt-out ficam de fora. |
scheduledAt | Data e hora de início (ISO 8601) ou null. |
minDelaySec, maxDelaySec | Intervalo aleatório entre contatos, em segundos. |
start | true para iniciar imediatamente. |
curl -X POST https://api.twmult.com/v1/campaigns \
-H "Authorization: Bearer $TWMULT_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Black Friday",
"steps": [
{ "type": "image", "mediaId": "clx3m4e5d", "text": "{Oi|Olá} {{primeiro_nome}}! 🔥 Só hoje: 30% off." },
{ "type": "text", "text": "Responda SAIR para não receber mais." }
],
"instanceIds": ["clx1a2b3c"],
"audience": { "all": false, "tags": ["vip"], "phones": ["5583999991234", "5583988887777"] },
"scheduledAt": null,
"minDelaySec": 8,
"maxDelaySec": 20,
"start": true
}'
Resposta 201, com a campanha no mesmo formato da listagem.
Com scheduledAt preenchido, a campanha fica agendada (SCHEDULED) e começa sozinha no horário. Sem start e sem agendamento, ela é criada como rascunho (DRAFT).
Pausar, retomar ou cancelar
POST/v1/campaigns/{id}/pause
POST/v1/campaigns/{id}/resume
POST/v1/campaigns/{id}/cancel
curl -X POST https://api.twmult.com/v1/campaigns/clx7f8g9h/pause \
-H "Authorization: Bearer $TWMULT_KEY"
Retorna a campanha atualizada.
Vendas
Listar pedidos
GET/v1/orders?status=PENDING|PAID|CANCELED
curl "https://api.twmult.com/v1/orders?status=PENDING" \
-H "Authorization: Bearer $TWMULT_KEY"
[
{
"id": "clx4o5r6d",
"number": 1042,
"items": [{ "productId": "clx8p9q0r", "name": "Croissant", "priceCents": 1200, "qty": 1 }],
"totalCents": 1200,
"status": "PENDING",
"contact": { "phone": "5583999991234", "name": "Ana" },
"createdAt": "2026-11-16T18:42:00.000Z"
}
]
Atualizar status do pedido
PATCH/v1/orders/{number}
Use o número do pedido (o mesmo que o cliente vê), não o id. Marcar como PAID dispara o webhook order.paid.
curl -X PATCH https://api.twmult.com/v1/orders/1042 \
-H "Authorization: Bearer $TWMULT_KEY" \
-H "Content-Type: application/json" \
-d '{ "status": "PAID" }'
Criar negociação no CRM
POST/v1/deals
Cria uma negociação no CRM. stage é o nome da etapa do funil; sem stage, ela vai para a primeira etapa.
curl -X POST https://api.twmult.com/v1/deals \
-H "Authorization: Bearer $TWMULT_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Plano anual",
"valueCents": 120000,
"phone": "5583999991234",
"stage": "Proposta"
}'
n8n, Make e Zapier
Use o nó ou módulo de requisição HTTP da ferramenta:
- Para chamar a API: método e URL do endpoint, cabeçalho
Authorization: Bearer <chave>e corpo JSON. - Para receber eventos: crie um gatilho do tipo webhook, copie a URL gerada e cadastre-a em Conta → Integrações → Webhooks. Veja Webhooks.