TWMULT Docs

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 basehttps://api.twmult.com/v1
FormatoJSON (exceto o upload de mídia, em multipart/form-data)
AutenticaçãoAuthorization: Bearer <chave>
Limite120 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" }
StatusQuando
401Chave ausente, inválida ou revogada.
402Limite do plano atingido ou assinatura suspensa.
404Recurso não encontrado.
422Erro de validação. O campo issues detalha cada problema.
429Mais 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

CampoTipoDescrição
phonestringObrigatório. Telefone do destinatário.
textstringTexto da mensagem. Com mídia, vira a legenda.
instanceIdstringOpcional. Conexão que vai enviar. Padrão: a primeira conexão ativa.
mediaobjetoOpcional. 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.

CampoDescrição
nameNome da campanha.
stepsMensagens 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.
instanceIdsConexõ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.
scheduledAtData e hora de início (ISO 8601) ou null.
minDelaySec, maxDelaySecIntervalo aleatório entre contatos, em segundos.
starttrue 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: