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.

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.

Escopo contacts:read

Parâmetros

NomeOndeDescrição
external_idcaminhostring

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.

Escopo contacts:write

Parâmetros

NomeOndeDescrição
external_idcaminhostring

Corpo

CampoTipoDescrição
name opcionalstring | null
phone opcionalstring | null
email opcionalstring | null
tags opcionalarray

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).

Escopo consents:write · exige Idempotency-Key

Parâmetros

NomeOndeDescrição
external_idcaminhostring

Corpo

CampoTipoDescrição
channelstring (whatsapp, email, instagram, messenger, telegram)
purposestring (marketing, utility)
evidencestring

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.

Escopo consents:write

Parâmetros

NomeOndeDescrição
external_idcaminhostring
channelcaminhostring
purposecaminhostring

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.

Escopo rewards:read

Parâmetros

NomeOndeDescrição
external_idcaminhostring

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.

Escopo rewards:write · exige Idempotency-Key

Parâmetros

NomeOndeDescrição
external_idcaminhostring

Corpo

CampoTipoDescrição
amount_centsintegerQuanto do crédito usar
purchase_cents opcionalinteger | nullValor da compra: confere a compra mínima de cada concessão
note opcionalstring | nullReferê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.

Escopo datasets:read

Parâmetros

NomeOndeDescrição
datasetcaminhoO identificador do dataset (ex.: carteira), como aparece no painel
external_idcaminhoO 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.

Escopo datasets:write

Parâmetros

NomeOndeDescrição
datasetcaminhoO identificador do dataset (ex.: carteira), como aparece no painel
external_idcaminhoO id da linha no seu sistema

Corpo

CampoTipoDescrição
valuesobjectOs 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 opcionalstring | nullO 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.

Escopo datasets:write

Parâmetros

NomeOndeDescrição
datasetcaminhoO identificador do dataset (ex.: carteira), como aparece no painel
external_idcaminhoO 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.

Escopo events:read

Parâmetros

NomeOndeDescrição
limit opcionalqueryinteger
starting_after opcionalquerystring
type opcionalquerySó 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.

Escopo webhooks:read

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.

Escopo webhooks:write · exige Idempotency-Key

Corpo

CampoTipoDescrição
namestring
urlstring
eventsarrayOs eventos que o endpoint recebe, ou ["*"] para todos (inclusive os que vierem)
customer_fields opcionalarrayCampos 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.

Escopo webhooks:read

Parâmetros

NomeOndeDescrição
idcaminhostring

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.

Escopo webhooks:write

Parâmetros

NomeOndeDescrição
idcaminhostring

Corpo

CampoTipoDescrição
name opcionalstring
url opcionalstring
events opcionalarrayOs eventos que o endpoint recebe, ou ["*"] para todos (inclusive os que vierem)
customer_fields opcionalarrayCampos do contato que vão no corpo: nome, telefone, email. Vazio: só os ids. Documento nunca sai.
enabled opcionalboolean

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.

Escopo webhooks:write

Parâmetros

NomeOndeDescrição
idcaminhostring

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).

Escopo webhooks:write

Parâmetros

NomeOndeDescrição
idcaminhostring

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.

Escopo webhooks:write

Parâmetros

NomeOndeDescrição
idcaminhostring

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.

Escopo webhooks:write · exige Idempotency-Key

Parâmetros

NomeOndeDescrição
idcaminhostring

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.

Escopo webhooks:write

Parâmetros

NomeOndeDescrição
idcaminhostring

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.

Escopo events:write · exige Idempotency-Key

Corpo

CampoTipoDescrição
typestringA chave do tipo de evento, como cadastrada
contactobject
data opcionalobjectOs 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.

Escopo events:read

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.

Escopo messages:write · exige Idempotency-Key

Corpo

CampoTipoDescrição
contactobject
channel_account_id opcionalstringO 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 opcionalstringTexto livre: só sai com a janela de 24 h aberta. Preço digitado é recusado (mande valores por um evento).
template opcionalobject

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.*.

Escopo messages:read

Parâmetros

NomeOndeDescrição
idcaminhostring

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.

Escopo messages:read

Parâmetros

NomeOndeDescrição
channel_account_id opcionalquerySó 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.

Escopo accounts:read

Parâmetros

NomeOndeDescrição
limit opcionalqueryinteger
starting_after opcionalquerystring

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.

Escopo accounts:write · exige Idempotency-Key

Corpo

CampoTipoDescrição
namestringNome da conta (ex.: o nome do consultório)
branding opcionalobject

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).

Escopo files:write · exige Idempotency-Key

Corpo

CampoTipoDescrição
filenamestringO nome do arquivo (ex.: holerite-2026-10.pdf)
content_base64stringO PDF em base64, até 10 MB já decodificado
kind opcionalstringA 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 opcionalstringA competência, aaaa-mm
contact_external_id opcionalstringO 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 opcionalstringO 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