Documentação da API

A Torqyn como camada de conversa do seu sistema

O seu sistema manda os contatos e os eventos. A Torqyn fala com a pessoa no WhatsApp da empresa, pela IA ou por um modelo aprovado, e devolve por webhook o que aconteceu: entregue, lida, respondida, pediu para sair.

Endereço, formato e versão

Toda chamada vai para https://platform.torqyn.com, com a chave no cabeçalho Authorization: Bearer.
Corpo e resposta em JSON (Content-Type: application/json). Erros vêm em application/problem+json, com um code estável (lista).
Toda resposta traz Torqyn-Request-Id e Torqyn-Version. Guarde o id quando algo der errado.
A especificação inteira está em openapi.json (OpenAPI 3.1), gerada do mesmo código que valida cada requisição.

Primeiros passos, em cinco minutos

A API é ligada pela Torqyn no contrato da sua empresa. Com ela ligada, o dono da conta vê Configurações → Desenvolvedores no painel, e tudo abaixo acontece na conta de teste: nenhuma mensagem sai para ninguém.

1. Crie uma chave de teste

Em Desenvolvedores → Chaves de API, crie uma chave do tipo Teste com os escopos contacts:write, events:write e webhooks:write. Ela começa com tq_test_ e aparece uma vez só: guarde no servidor do seu sistema.

2. Confira a chave

curl https://platform.torqyn.com/v1/ping \
  -H "Authorization: Bearer $TORQYN_KEY"

A resposta diz a conta e "livemode": false: é a conta de teste.

3. Mande um contato

O contato é identificado pelo id dele no seu sistema. O número abaixo é um dos números de teste: a mensagem é entregue e lida, sem sair da Torqyn.

curl -X PUT https://platform.torqyn.com/v1/contacts/cliente-42 \
  -H "Authorization: Bearer $TORQYN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Ana Martins", "phone": "+5511900000001"}'

4. Cadastre um tipo de evento e mande

Em Desenvolvedores → Tipos de evento, crie um tipo (por exemplo consulta_amanha, com a variável horario) e diga como falar: a instrução para a IA e, para quando a janela de 24 horas do WhatsApp estiver fechada, um modelo aprovado. Depois:

curl -X POST https://platform.torqyn.com/v1/events \
  -H "Authorization: Bearer $TORQYN_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2b1e-lembrete-cliente-42" \
  -d '{"type": "consulta_amanha", "contact": {"external_id": "cliente-42"}, "data": {"horario": "2026-10-02T14:00:00-03:00"}}'

A resposta diz se saiu (delivered), por onde (ai ou template) e, se não saiu, o motivo.

5. Receba o que aconteceu

Em Desenvolvedores → Webhooks, crie um endpoint de teste com o endereço do seu sistema e escolha message.delivered e message.read. Clique em "Enviar evento de teste" para conferir o endereço e a assinatura. A partir daí, cada mensagem entregue e lida chega lá.

O que existe hoje

Rota	O que faz
GET `/v1/ping`	Conferir a chave
GET `/v1/contacts/{external_id}`	Ler um contato
PUT `/v1/contacts/{external_id}`	Criar ou atualizar um contato
POST `/v1/contacts/{external_id}/consents`	Registrar um consentimento
DELETE `/v1/contacts/{external_id}/consents/{channel}/{purpose}`	Revogar um consentimento
GET `/v1/events`	Listar os eventos dos últimos 30 dias
POST `/v1/events`	Mandar um evento
GET `/v1/event-types`	Listar os tipos de evento
GET `/v1/webhook-endpoints`	Listar os endpoints de webhook
POST `/v1/webhook-endpoints`	Criar um endpoint de webhook
GET `/v1/webhook-endpoints/{id}`	Ler um endpoint de webhook
PATCH `/v1/webhook-endpoints/{id}`	Mudar um endpoint de webhook
DELETE `/v1/webhook-endpoints/{id}`	Desligar um endpoint de webhook
POST `/v1/webhook-endpoints/{id}/pause`	Pausar um endpoint
POST `/v1/webhook-endpoints/{id}/resume`	Reativar um endpoint
POST `/v1/webhook-endpoints/{id}/rotate-secret`	Trocar o segredo de um endpoint
POST `/v1/webhook-endpoints/{id}/test`	Mandar um evento de teste

O detalhe de cada rota (parâmetros, corpo, exemplo de resposta e erros) está na referência.