Referência
Todas as rotas
Gerada do mesmo registro de rotas que valida cada requisição. Para usar num gerador de cliente ou no Postman, baixe o openapi.json.
Base: https://platform.torqyn.com. Toda rota aceita o cabeçalho Torqyn-Version.
Começar
GET /v1/ping
Conferir a chave
Responde com a conta, o modo (teste ou produção) e a versão da API. Serve para conferir a chave e a conexão antes de integrar; não pede escopo.
Resposta 200
{
"object": "ping",
"account": "0f6a3c1e-2b4d-4e8a-9c21-7d4e5f6a8b90",
"livemode": false,
"api_version": "2026-10-01"
}
Erros possíveis: invalid_request, invalid_version, unauthorized, rate_limited, internal_error
Contatos
GET /v1/contacts/{external_id}
Ler um contato
O contato pelo id do seu sistema, com as etiquetas e os consentimentos em vigor. Documento (CPF/CNPJ) nunca sai pela API.
Parâmetros
| Nome | Onde | Descrição |
|---|---|---|
external_id | caminho | string |
Resposta 200
{
"object": "contact",
"id": "6f1c2a90-5b3e-4d7a-9e12-3c4b5a6d7e8f",
"external_id": "fam-123",
"name": "Ana Martins",
"phone": "+5583999998888",
"email": "ana@exemplo.com.br",
"tags": [
"Plano família"
],
"opted_out": false,
"client_status": "client",
"client_since": "2026-10-01T12:00:00.000Z",
"consents": [
{
"channel": "whatsapp",
"purpose": "utility",
"origin": "api",
"granted_at": "2026-10-01T12:00:00.000Z"
}
],
"created_at": "2026-10-01T12:00:00.000Z",
"updated_at": "2026-10-01T12:00:00.000Z"
}
Erros possíveis: invalid_request, invalid_version, unauthorized, forbidden_scope, not_found, rate_limited, internal_error
PUT /v1/contacts/{external_id}
Criar ou atualizar um contato
Cria o contato pelo id do seu sistema, ou atualiza se ele já existe. Campo omitido fica como está; null apaga. O telefone e o e-mail que vêm do seu sistema contam como confirmados, e o contato se liga sozinho à conversa que a mesma pessoa já tem pelo WhatsApp. tags (pelo nome, como cadastradas no painel) passa a ser a lista de etiquetas que a API pôs: as que saírem da lista são tiradas; as que o time pôs à mão, nunca.
Parâmetros
| Nome | Onde | Descrição |
|---|---|---|
external_id | caminho | string |
Corpo
| Campo | Tipo | Descrição |
|---|---|---|
name opcional | string | null | |
phone opcional | string | null | |
email opcional | string | null | |
tags opcional | array |
Resposta 200
{
"object": "contact",
"id": "6f1c2a90-5b3e-4d7a-9e12-3c4b5a6d7e8f",
"external_id": "fam-123",
"name": "Ana Martins",
"phone": "+5583999998888",
"email": "ana@exemplo.com.br",
"tags": [
"Plano família"
],
"opted_out": false,
"client_status": "client",
"client_since": "2026-10-01T12:00:00.000Z",
"consents": [
{
"channel": "whatsapp",
"purpose": "utility",
"origin": "api",
"granted_at": "2026-10-01T12:00:00.000Z"
}
],
"created_at": "2026-10-01T12:00:00.000Z",
"updated_at": "2026-10-01T12:00:00.000Z"
}
Erros possíveis: invalid_request, invalid_version, unauthorized, forbidden_scope, not_found, payload_too_large, unsupported_media_type, rate_limited, internal_error
POST /v1/contacts/{external_id}/consents
Registrar um consentimento
Registra que a pessoa aceitou receber mensagem num canal e para uma finalidade, com a evidência de como aceitou no seu sistema. marketing é o que permite mandar oferta e novidade; utility é o serviço de algo que ela já contratou. Quem pediu para sair não recebe consentimento pela API (opted_out).
Parâmetros
| Nome | Onde | Descrição |
|---|---|---|
external_id | caminho | string |
Corpo
| Campo | Tipo | Descrição |
|---|---|---|
channel | string (whatsapp, email, instagram, messenger, telegram) | |
purpose | string (marketing, utility) | |
evidence | string |
Resposta 201
{
"object": "contact",
"id": "6f1c2a90-5b3e-4d7a-9e12-3c4b5a6d7e8f",
"external_id": "fam-123",
"name": "Ana Martins",
"phone": "+5583999998888",
"email": "ana@exemplo.com.br",
"tags": [
"Plano família"
],
"opted_out": false,
"client_status": "client",
"client_since": "2026-10-01T12:00:00.000Z",
"consents": [
{
"channel": "whatsapp",
"purpose": "utility",
"origin": "api",
"granted_at": "2026-10-01T12:00:00.000Z"
}
],
"created_at": "2026-10-01T12:00:00.000Z",
"updated_at": "2026-10-01T12:00:00.000Z"
}
Erros possíveis: invalid_request, invalid_version, idempotency_key_required, unauthorized, forbidden_scope, not_found, idempotency_key_in_use, payload_too_large, unsupported_media_type, idempotency_key_reused, rate_limited, internal_error
DELETE /v1/contacts/{external_id}/consents/{channel}/{purpose}
Revogar um consentimento
Revoga o consentimento daquele canal e finalidade. O registro não é apagado: fica como prova do período em que valeu.
Parâmetros
| Nome | Onde | Descrição |
|---|---|---|
external_id | caminho | string |
channel | caminho | string |
purpose | caminho | string |
Resposta 200
{
"object": "contact",
"id": "6f1c2a90-5b3e-4d7a-9e12-3c4b5a6d7e8f",
"external_id": "fam-123",
"name": "Ana Martins",
"phone": "+5583999998888",
"email": "ana@exemplo.com.br",
"tags": [
"Plano família"
],
"opted_out": false,
"client_status": "client",
"client_since": "2026-10-01T12:00:00.000Z",
"consents": [],
"created_at": "2026-10-01T12:00:00.000Z",
"updated_at": "2026-10-01T12:00:00.000Z"
}
Erros possíveis: invalid_request, invalid_version, unauthorized, forbidden_scope, not_found, rate_limited, internal_error
Recompensas
GET /v1/contacts/{external_id}/rewards
Ler o saldo de recompensas
O crédito do contato (indicação e cashback), com o que vence nos próximos 7 dias e cada concessão com a validade e a compra mínima. O saldo é calculado pela Torqyn a partir do livro de recompensas: não guarde uma cópia do seu lado.
Parâmetros
| Nome | Onde | Descrição |
|---|---|---|
external_id | caminho | string |
Resposta 200
{
"object": "rewards",
"external_id": "cli-123",
"available_cents": 3500,
"expiring_cents": 1500,
"next_expiry": "2026-10-20T03:00:00.000Z",
"grants": [
{
"id": "0a8f1d5e-3c2b-4e6a-9f7d-1b2c3d4e5f60",
"remaining_cents": 1500,
"expires_at": "2026-10-20T03:00:00.000Z",
"min_spend_cents": 10000
},
{
"id": "1b9e2c6f-4d3a-4f7b-8e6c-2a3b4c5d6e7f",
"remaining_cents": 2000,
"expires_at": null,
"min_spend_cents": 0
}
]
}
Erros possíveis: invalid_request, invalid_version, unauthorized, forbidden_scope, not_found, rate_limited, internal_error
POST /v1/contacts/{external_id}/rewards/redeem
Usar o crédito numa compra
Debita o crédito do contato numa compra. Vale o crédito ainda dentro da validade e cuja compra mínima a compra alcança (purchase_cents); pedir mais do que isso é recusado inteiro (conflict), nunca pela metade. A mesma Idempotency-Key nunca debita duas vezes.
Parâmetros
| Nome | Onde | Descrição |
|---|---|---|
external_id | caminho | string |
Corpo
| Campo | Tipo | Descrição |
|---|---|---|
amount_cents | integer | Quanto do crédito usar |
purchase_cents opcional | integer | null | Valor da compra: confere a compra mínima de cada concessão |
note opcional | string | null | Referência curta (ex.: número do pedido) |
Resposta 201
{
"object": "redemption",
"id": "2c0f3d7a-5e4b-4a8c-9d6e-3b4c5d6e7f80",
"external_id": "cli-123",
"amount_cents": 1500,
"balance_cents": 2000,
"replayed": false
}
Erros possíveis: invalid_request, invalid_version, idempotency_key_required, unauthorized, forbidden_scope, not_found, idempotency_key_in_use, payload_too_large, unsupported_media_type, idempotency_key_reused, rate_limited, internal_error
Datasets
GET /v1/datasets/{dataset}/records/{external_id}
Ler uma linha de dataset
A linha pelo id do seu sistema. Coluna marcada como sensível nunca sai pela API.
Parâmetros
| Nome | Onde | Descrição |
|---|---|---|
dataset | caminho | O identificador do dataset (ex.: carteira), como aparece no painel |
external_id | caminho | O id da linha no seu sistema |
Resposta 200
{
"object": "dataset_record",
"id": "0c7e5b1a-6a2f-4a8f-b8d5-1f2e3d4c5b6a",
"external_id": "12.345.678/0001-90",
"values": {
"regime": "Simples",
"documentos_mes": false,
"vencimento_das": "2026-10-20"
},
"linked_to_contact": true,
"updated_at": "2026-10-08T12:00:00.000Z"
}
Erros possíveis: invalid_request, invalid_version, unauthorized, forbidden_scope, not_found, rate_limited, internal_error
PUT /v1/datasets/{dataset}/records/{external_id}
Criar ou atualizar uma linha de dataset
Cria a linha pelo id do seu sistema, ou atualiza se ela já existe. Só vale para dataset com a fonte "API", criado no painel. Coluna que não existe no dataset é recusada; coluna omitida fica vazia. Valor em dinheiro é guardado como o registrado, nunca vira preço de venda.
Parâmetros
| Nome | Onde | Descrição |
|---|---|---|
dataset | caminho | O identificador do dataset (ex.: carteira), como aparece no painel |
external_id | caminho | O id da linha no seu sistema |
Corpo
| Campo | Tipo | Descrição |
|---|---|---|
values | object | Os valores pela chave da coluna. Valor em reais como número (76.6) ou texto ("76,60"); data como "aaaa-mm-dd" ou "dd/mm/aaaa"; sim/não como booleano. |
contact opcional | string | null | O valor que liga a linha ao contato (telefone, e-mail ou código, conforme o dataset). Só no dataset por contato. |
Resposta 200
{
"object": "dataset_record",
"id": "0c7e5b1a-6a2f-4a8f-b8d5-1f2e3d4c5b6a",
"external_id": "12.345.678/0001-90",
"values": {
"regime": "Simples",
"documentos_mes": false,
"vencimento_das": "2026-10-20"
},
"linked_to_contact": true,
"updated_at": "2026-10-08T12:00:00.000Z"
}
Erros possíveis: invalid_request, invalid_version, unauthorized, forbidden_scope, not_found, payload_too_large, unsupported_media_type, rate_limited, internal_error
DELETE /v1/datasets/{dataset}/records/{external_id}
Remover uma linha de dataset
Tira a linha do dataset: a IA e os públicos deixam de vê-la na hora, e ela é apagada de vez em 30 dias.
Parâmetros
| Nome | Onde | Descrição |
|---|---|---|
dataset | caminho | O identificador do dataset (ex.: carteira), como aparece no painel |
external_id | caminho | O id da linha no seu sistema |
Resposta 200
{
"object": "dataset_record",
"deleted": true
}
Erros possíveis: invalid_request, invalid_version, unauthorized, forbidden_scope, not_found, rate_limited, internal_error
Webhooks
GET /v1/events
Listar os eventos dos últimos 30 dias
Os eventos que saíram (ou sairiam) pelos webhooks nos últimos 30 dias, do mais novo para o mais antigo, no mesmo envelope, sem campo pessoal do contato (só os ids). Serve para conferir o que o seu endpoint perdeu. Filtre por type.
Parâmetros
| Nome | Onde | Descrição |
|---|---|---|
limit opcional | query | integer |
starting_after opcional | query | string |
type opcional | query | Só um tipo de evento |
Resposta 200
{
"object": "list",
"data": [
{
"id": "0f6a3c1e-8b2d-4e5f-9a1b-2c3d4e5f6a7b",
"type": "message.delivered",
"api_version": "2026-10-01",
"created": "2026-10-02T10:15:03.000Z",
"livemode": false,
"account": "1a2b3c4d-5e6f-4a8b-9c0d-1e2f3a4b5c6d",
"data": {
"object": {
"object": "message",
"id": "3a5c7e9b-1d2f-4a6b-8c0d-2e4f6a8b0c1d",
"direction": "outbound",
"status": "delivered",
"conversation_id": "9b2f4c1e-7d3a-4e5f-8a6b-1c2d3e4f5a6b",
"channel": "whatsapp",
"contact": {
"id": "5b7c2d1e-8f3a-4b6c-9d2e-1f4a5b6c7d8e",
"external_id": "fam-123"
}
}
}
}
],
"has_more": false
}
Erros possíveis: invalid_request, invalid_version, unauthorized, forbidden_scope, rate_limited, internal_error
GET /v1/webhook-endpoints
Listar os endpoints de webhook
Os endpoints desta conta (a de teste ou a de produção, pela chave), sem o segredo. Inclui os desligados.
Resposta 200
{
"object": "list",
"data": [
{
"object": "webhook_endpoint",
"id": "4d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a",
"name": "Meu sistema",
"url": "https://api.seusistema.com.br/torqyn",
"events": [
"message.delivered",
"message.failed",
"appointment.created"
],
"customer_fields": [],
"api_version": "2026-10-01",
"status": "active",
"pause_reason": null,
"previous_secret_valid_until": null,
"livemode": false,
"created_at": "2026-10-01T12:00:00.000Z"
}
],
"has_more": false
}
Erros possíveis: invalid_request, invalid_version, unauthorized, forbidden_scope, rate_limited, internal_error
POST /v1/webhook-endpoints
Criar um endpoint de webhook
Cria o endpoint e devolve o segredo whsec_… **só nesta resposta**: guarde-o para conferir a assinatura (Torqyn-Signature). A URL precisa ser https e resolver para um endereço público. A versão do corpo fica presa à versão desta requisição.
Corpo
| Campo | Tipo | Descrição |
|---|---|---|
name | string | |
url | string | |
events | array | Os eventos que o endpoint recebe, ou ["*"] para todos (inclusive os que vierem) |
customer_fields opcional | array | Campos do contato que vão no corpo: nome, telefone, email. Vazio: só os ids. Documento nunca sai. |
Resposta 201
{
"object": "webhook_endpoint",
"id": "4d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a",
"name": "Meu sistema",
"url": "https://api.seusistema.com.br/torqyn",
"events": [
"message.delivered",
"message.failed",
"appointment.created"
],
"customer_fields": [],
"api_version": "2026-10-01",
"status": "active",
"pause_reason": null,
"previous_secret_valid_until": null,
"livemode": false,
"created_at": "2026-10-01T12:00:00.000Z",
"secret": "whsec_6q2Jb0xVn3cKp9sT1mRw4yZa7uEo5iLd"
}
Erros possíveis: invalid_request, invalid_version, idempotency_key_required, unauthorized, forbidden_scope, idempotency_key_in_use, payload_too_large, unsupported_media_type, idempotency_key_reused, rate_limited, internal_error
GET /v1/webhook-endpoints/{id}
Ler um endpoint de webhook
O endpoint, sem o segredo.
Parâmetros
| Nome | Onde | Descrição |
|---|---|---|
id | caminho | string |
Resposta 200
{
"object": "webhook_endpoint",
"id": "4d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a",
"name": "Meu sistema",
"url": "https://api.seusistema.com.br/torqyn",
"events": [
"message.delivered",
"message.failed",
"appointment.created"
],
"customer_fields": [],
"api_version": "2026-10-01",
"status": "active",
"pause_reason": null,
"previous_secret_valid_until": null,
"livemode": false,
"created_at": "2026-10-01T12:00:00.000Z"
}
Erros possíveis: invalid_request, invalid_version, unauthorized, forbidden_scope, not_found, rate_limited, internal_error
PATCH /v1/webhook-endpoints/{id}
Mudar um endpoint de webhook
Troca nome, URL, eventos ou campos do contato. enabled: true religa um endpoint desligado. Para pausar e reativar, use as rotas próprias; para trocar o segredo, rotate-secret.
Parâmetros
| Nome | Onde | Descrição |
|---|---|---|
id | caminho | string |
Corpo
| Campo | Tipo | Descrição |
|---|---|---|
name opcional | string | |
url opcional | string | |
events opcional | array | Os eventos que o endpoint recebe, ou ["*"] para todos (inclusive os que vierem) |
customer_fields opcional | array | Campos do contato que vão no corpo: nome, telefone, email. Vazio: só os ids. Documento nunca sai. |
enabled opcional | boolean |
Resposta 200
{
"object": "webhook_endpoint",
"id": "4d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a",
"name": "Meu sistema",
"url": "https://api.seusistema.com.br/torqyn",
"events": [
"message.delivered",
"message.failed",
"appointment.created"
],
"customer_fields": [],
"api_version": "2026-10-01",
"status": "active",
"pause_reason": null,
"previous_secret_valid_until": null,
"livemode": false,
"created_at": "2026-10-01T12:00:00.000Z"
}
Erros possíveis: invalid_request, invalid_version, unauthorized, forbidden_scope, not_found, payload_too_large, unsupported_media_type, rate_limited, internal_error
DELETE /v1/webhook-endpoints/{id}
Desligar um endpoint de webhook
Desliga o endpoint: para de receber eventos, e o histórico de entregas fica. Religue com PATCH e enabled: true.
Parâmetros
| Nome | Onde | Descrição |
|---|---|---|
id | caminho | string |
Resposta 200
{
"object": "webhook_endpoint",
"id": "4d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a",
"name": "Meu sistema",
"url": "https://api.seusistema.com.br/torqyn",
"events": [
"message.delivered",
"message.failed",
"appointment.created"
],
"customer_fields": [],
"api_version": "2026-10-01",
"status": "disabled",
"pause_reason": null,
"previous_secret_valid_until": null,
"livemode": false,
"created_at": "2026-10-01T12:00:00.000Z"
}
Erros possíveis: invalid_request, invalid_version, unauthorized, forbidden_scope, not_found, rate_limited, internal_error
POST /v1/webhook-endpoints/{id}/pause
Pausar um endpoint
As entregas param e esperam na fila até reativar (útil durante uma manutenção do seu lado).
Parâmetros
| Nome | Onde | Descrição |
|---|---|---|
id | caminho | string |
Resposta 200
{
"object": "webhook_endpoint",
"id": "4d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a",
"name": "Meu sistema",
"url": "https://api.seusistema.com.br/torqyn",
"events": [
"message.delivered",
"message.failed",
"appointment.created"
],
"customer_fields": [],
"api_version": "2026-10-01",
"status": "paused",
"pause_reason": "pausado pelo dono",
"previous_secret_valid_until": null,
"livemode": false,
"created_at": "2026-10-01T12:00:00.000Z"
}
Erros possíveis: invalid_request, invalid_version, unauthorized, forbidden_scope, not_found, rate_limited, internal_error
POST /v1/webhook-endpoints/{id}/resume
Reativar um endpoint
Volta a entregar o que ficou na fila, inclusive depois da pausa automática por falhas seguidas.
Parâmetros
| Nome | Onde | Descrição |
|---|---|---|
id | caminho | string |
Resposta 200
{
"object": "webhook_endpoint",
"id": "4d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a",
"name": "Meu sistema",
"url": "https://api.seusistema.com.br/torqyn",
"events": [
"message.delivered",
"message.failed",
"appointment.created"
],
"customer_fields": [],
"api_version": "2026-10-01",
"status": "active",
"pause_reason": null,
"previous_secret_valid_until": null,
"livemode": false,
"created_at": "2026-10-01T12:00:00.000Z"
}
Erros possíveis: invalid_request, invalid_version, unauthorized, forbidden_scope, not_found, rate_limited, internal_error
POST /v1/webhook-endpoints/{id}/rotate-secret
Trocar o segredo de um endpoint
Gera um segredo novo, devolvido só nesta resposta. Por 24 h cada entrega leva as duas assinaturas (v1=<novo>,v1=<anterior>): troque o segredo no seu sistema nesse meio-tempo, sem perder nenhum evento.
Parâmetros
| Nome | Onde | Descrição |
|---|---|---|
id | caminho | string |
Resposta 200
{
"object": "webhook_secret",
"secret": "whsec_9aT3kLp0Qz7xVb2Nc5Rm8Wd1Ye4Hf6Us",
"previous_secret_valid_until": "2026-10-02T12:00:00.000Z"
}
Erros possíveis: invalid_request, invalid_version, idempotency_key_required, unauthorized, forbidden_scope, not_found, idempotency_key_in_use, idempotency_key_reused, rate_limited, internal_error
POST /v1/webhook-endpoints/{id}/test
Mandar um evento de teste
Manda agora um evento ping, assinado como os outros, e devolve o que o seu servidor respondeu. Não conta para a pausa por falhas.
Parâmetros
| Nome | Onde | Descrição |
|---|---|---|
id | caminho | string |
Resposta 200
{
"object": "webhook_test",
"ok": true,
"status": 200,
"duration_ms": 84,
"error": null
}
Erros possíveis: invalid_request, invalid_version, unauthorized, forbidden_scope, not_found, rate_limited, internal_error
Eventos
POST /v1/events
Mandar um evento
Manda um evento de um tipo cadastrado para um contato. Com a janela de 24 h do WhatsApp aberta e a IA atendendo, a IA escreve seguindo a instrução do tipo; senão sai o modelo aprovado do tipo. O que impede o envio (sem telefone, sem canal, fora da janela sem modelo, modelo não aprovado, sem consentimento de marketing) volta com status: failed e o motivo. Quem pediu para sair nunca recebe: a resposta é opted_out e nada sai. O mesmo evento duas vezes, com a mesma Idempotency-Key, sai uma vez.
Corpo
| Campo | Tipo | Descrição |
|---|---|---|
type | string | A chave do tipo de evento, como cadastrada |
contact | object | |
data opcional | object | Os valores das variáveis do tipo; datas em ISO 8601 |
Resposta 202
{
"object": "event",
"type": "consulta_amanha",
"contact": {
"external_id": "fam-123"
},
"status": "delivered",
"reason": null,
"detail": null,
"via": "template",
"channel": "whatsapp",
"conversation_id": "9b2f4c1e-7d3a-4e5f-8a6b-1c2d3e4f5a6b"
}
Erros possíveis: invalid_request, invalid_version, idempotency_key_required, unauthorized, forbidden_scope, not_found, idempotency_key_in_use, opted_out, payload_too_large, unsupported_media_type, idempotency_key_reused, rate_limited, internal_error
GET /v1/event-types
Listar os tipos de evento
Os tipos de evento cadastrados nesta conta, com as variáveis que cada um espera. Cadastrar e mudar é no painel, em Configurações → Desenvolvedores.
Resposta 200
{
"object": "list",
"data": [
{
"object": "event_type",
"type": "consulta_amanha",
"description": "Lembrete da consulta do dia seguinte",
"variables": [
{
"name": "data_consulta",
"type": "date",
"example": "2026-10-02T15:00:00-03:00",
"required": true
},
{
"name": "medico",
"type": "text",
"example": "Dra. Ana",
"required": true
}
],
"speaks_with": [
"ai",
"template"
]
}
]
}
Erros possíveis: invalid_request, invalid_version, unauthorized, forbidden_scope, rate_limited, internal_error
Mensagens
POST /v1/messages
Mandar uma mensagem
Manda uma mensagem de WhatsApp para um contato: um modelo aprovado a qualquer hora, ou texto livre só com a janela de 24 h aberta (a pessoa escreveu nas últimas 24 h). A mensagem fica na conversa como fala do time, com autor "API", e não cala a IA. Quem pediu para sair nunca recebe (opted_out); texto fora da janela é outside_window; modelo de marketing sem consentimento é no_consent; modelo que não existe no número ou não está aprovado é template_not_approved. Nada disso envia. A mesma Idempotency-Key manda uma vez só. Com uma chave tq_test_, sai pelo canal simulado da conta de teste.
Corpo
| Campo | Tipo | Descrição |
|---|---|---|
contact | object | |
channel_account_id opcional | string | O número que manda (veja GET /v1/templates). Sem ele: o da conversa mais recente com a pessoa, senão o primeiro conectado; com modelo, só número que tem o modelo. |
text opcional | string | Texto livre: só sai com a janela de 24 h aberta. Preço digitado é recusado (mande valores por um evento). |
template opcional | object |
Resposta 202
{
"object": "message",
"id": "3d6f9a12-4b7c-4e8d-9f01-2a3b4c5d6e7f",
"type": "template",
"status": "sent",
"template": {
"name": "lembrete_consulta",
"language": "pt_BR"
},
"contact": {
"external_id": "fam-123"
},
"channel": "whatsapp",
"channel_account_id": "8a7b6c5d-4e3f-4a1b-9c2d-0e1f2a3b4c5d",
"conversation_id": "9b2f4c1e-7d3a-4e5f-8a6b-1c2d3e4f5a6b",
"created_at": "2026-10-01T12:00:00.000Z"
}
Erros possíveis: invalid_request, invalid_version, idempotency_key_required, unauthorized, forbidden_scope, not_found, idempotency_key_in_use, opted_out, outside_window, no_consent, template_not_approved, no_channel, no_phone, blocked, payload_too_large, unsupported_media_type, idempotency_key_reused, rate_limited, internal_error
GET /v1/messages/{id}
Ver o status de uma mensagem
O status de agora de uma mensagem mandada pela API (enviada, entregue, lida ou não entregue). Mensagem que não foi mandada pela API responde 404. Para não perguntar, assine os webhooks message.*.
Parâmetros
| Nome | Onde | Descrição |
|---|---|---|
id | caminho | string |
Resposta 200
{
"object": "message",
"id": "3d6f9a12-4b7c-4e8d-9f01-2a3b4c5d6e7f",
"type": "template",
"status": "read",
"template": {
"name": "lembrete_consulta",
"language": "pt_BR"
},
"contact": {
"external_id": "fam-123"
},
"channel": "whatsapp",
"channel_account_id": "8a7b6c5d-4e3f-4a1b-9c2d-0e1f2a3b4c5d",
"conversation_id": "9b2f4c1e-7d3a-4e5f-8a6b-1c2d3e4f5a6b",
"created_at": "2026-10-01T12:00:00.000Z"
}
Erros possíveis: invalid_request, invalid_version, unauthorized, forbidden_scope, not_found, rate_limited, internal_error
GET /v1/templates
Listar os modelos por número
Os modelos de mensagem de cada número conectado, com o status na Meta e as variáveis. Modelo de marketing só sai para quem tem consentimento de marketing registrado. Criar e mudar modelo é no painel, em Configurações → Modelos.
Parâmetros
| Nome | Onde | Descrição |
|---|---|---|
channel_account_id opcional | query | Só os modelos deste número |
Resposta 200
{
"object": "list",
"data": [
{
"object": "template",
"id": "5e4d3c2b-1a09-4f8e-8d7c-6b5a4f3e2d1c",
"name": "lembrete_consulta",
"language": "pt_BR",
"category": "UTILITY",
"status": "approved",
"body": "Olá, {{1}}! Sua consulta é em {{2}}.",
"variables": [
{
"index": 1,
"example": "Ana",
"max_length": null
},
{
"index": 2,
"example": "02/10 15:00",
"max_length": null
}
],
"channel_account": {
"id": "8a7b6c5d-4e3f-4a1b-9c2d-0e1f2a3b4c5d",
"kind": "whatsapp",
"phone": "+55 83 95278-7787"
}
}
]
}
Erros possíveis: invalid_request, invalid_version, unauthorized, forbidden_scope, rate_limited, internal_error
Contas
GET /v1/accounts
Listar as contas
A conta principal e as contas filhas da parceira, das mais antigas para as mais novas, com os números de WhatsApp de cada uma. Com a chave de teste, os números são os simulados das gêmeas. Pede chave de parceiro.
Parâmetros
| Nome | Onde | Descrição |
|---|---|---|
limit opcional | query | integer |
starting_after opcional | query | string |
Resposta 200
{
"object": "list",
"data": [
{
"object": "account",
"id": "3a9d2c10-7e4b-4f1a-8b6c-5d2e1f0a9b8c",
"name": "Dra. Ana Pediatria",
"principal": false,
"status": "active",
"branding": {
"color": "#0e7490",
"logo_url": null,
"assistant_name": "Assistente da Dra. Ana"
},
"numbers": [],
"created_at": "2026-10-01T12:00:00.000Z"
}
],
"has_more": false
}
Erros possíveis: invalid_request, invalid_version, unauthorized, forbidden_scope, rate_limited, internal_error
POST /v1/accounts
Criar uma conta filha
Cria uma conta para um cliente seu (por exemplo, cada consultório), com marca própria e os recursos e o playbook da conta principal como ponto de partida. A conta nasce isolada das outras — uma nunca vê o contato da outra — e já com a gêmea de teste. Pede chave de parceiro de produção; depois, use o id no cabeçalho Torqyn-Account para agir nela (com a chave de teste, a mesma conta abre a gêmea). O número de WhatsApp de cada conta é conectado pela Torqyn.
Corpo
| Campo | Tipo | Descrição |
|---|---|---|
name | string | Nome da conta (ex.: o nome do consultório) |
branding opcional | object |
Resposta 201
{
"object": "account",
"id": "3a9d2c10-7e4b-4f1a-8b6c-5d2e1f0a9b8c",
"name": "Dra. Ana Pediatria",
"principal": false,
"status": "active",
"branding": {
"color": "#0e7490",
"logo_url": null,
"assistant_name": "Assistente da Dra. Ana"
},
"numbers": [],
"created_at": "2026-10-01T12:00:00.000Z"
}
Erros possíveis: invalid_request, invalid_version, idempotency_key_required, unauthorized, forbidden_scope, idempotency_key_in_use, payload_too_large, unsupported_media_type, idempotency_key_reused, rate_limited, internal_error
Arquivos
POST /v1/files
Mandar um PDF para entregar a um contato
Guarda o PDF (até 10 MB) no tipo informado e o liga ao contato. Com contact_external_id o dono é esse contato; sem ele, a Torqyn casa pelo nome do arquivo e pelo CPF/CNPJ do texto do PDF, e o que não casa fica em "Sem dono" no painel. O mesmo PDF para o mesmo contato e tipo não duplica, e external_id repetido devolve o arquivo que já existe. A entrega ao contato é pela rotina ou comunicado {{arquivo:<tipo>}} do painel. O corpo pode passar de 1 MB (até cerca de 14 MB em base64).
Corpo
| Campo | Tipo | Descrição |
|---|---|---|
filename | string | O nome do arquivo (ex.: holerite-2026-10.pdf) |
content_base64 | string | O PDF em base64, até 10 MB já decodificado |
kind opcional | string | A chave do tipo de arquivo, como aparece no painel (Arquivos → Tipos). Sem ela, a IA identifica o tipo pelo conteúdo e o arquivo é recusado se não houver confiança. |
period opcional | string | A competência, aaaa-mm |
contact_external_id opcional | string | O external_id do contato (o mesmo de PUT /v1/contacts). Sem ele, o dono sai do nome do arquivo e do CPF/CNPJ do PDF. |
external_id opcional | string | O id do arquivo no seu sistema: mandar de novo o mesmo id não duplica |
Resposta 201
{
"object": "file",
"id": "0c7e5b1a-6a2f-4a8f-b8d5-1f2e3d4c5b6a",
"status": "assigned",
"reason": null
}
Erros possíveis: invalid_request, invalid_version, idempotency_key_required, unauthorized, forbidden_scope, not_found, idempotency_key_in_use, payload_too_large, unsupported_media_type, idempotency_key_reused, rate_limited, internal_error