Primeiros passos

Documentação completa da API

Integre o Zyron Connect Suite com n8n, backends próprios, CRMs externos e rotinas internas usando endpoints REST versionados.

Visão geral

A API v1 trabalha sempre dentro da conta dona da chave. Toda listagem, criação, atualização e envio é limitado aos recursos do usuário autenticado pela chave Bearer.

URL base

Use sempre a URL completa abaixo. Os exemplos desta documentação já vêm prontos para copiar.

https://connect.zyronstack.com/api/v1

Autenticação

Envie o header Authorization em todas as chamadas. Crie a chave em Dashboard > API. Chaves novas podem ser visualizadas novamente no painel após confirmação da senha do usuário.

Authorization: Bearer SUA_CHAVE_API

Limite de requisições

O limite é por chave e por plano: 120 requisições por minuto nos planos Básico e Oficial, 300 no Agency. Ao exceder, a API retorna HTTP 429 com o header Retry-After informando quantos segundos aguardar.

Paginação

Listagens aceitam limit e offset. O retorno inclui pagination.limit, pagination.offset, pagination.total e pagination.next_offset.

OpenAPI JSON

GET https://connect.zyronstack.com/api/v1/openapi.json

OpenAPI JSON

Monte seus exemplos

Cole os valores da sua conta uma vez

Os exemplos não usam UUIDs fictícios: onde faltar um valor, aparece <NOME_DO_VALOR>. A chave fica só na memória deste navegador.

Sua chave de APICole aqui: os botões Copiar usam esta chave apenas nesta página.URL baseNormalmente não precisa alterar.connection_idCopie de GET /connections.conversation_idVem do webhook Zyron ou da busca de conversa.media_idVem da mensagem recebida ou do upload.

Identifique a conexão

Copie connection_id em GET /connections.

Envie ou faça upload

Use o guia do tipo: texto, imagem, áudio, documento ou template.

Acompanhe a entrega

O 202 apenas aceita; consulte o status pelo wamid.

Baixe mídia recebida

Leia a mensagem, consulte GET /media/:id e chame a URL de download.

Primeiros passos

Erros

Falhas retornam JSON padronizado com error.code e error.message.

400 invalid_body / query_error	JSON inválido ou falha de consulta
401 unauthorized	chave ausente, inválida ou revogada
403 forbidden	a chave não possui o escopo exigido
403 upgrade_required	o recurso exige plano Oficial ou Agency
404 not_found	recurso não encontrado na conta autenticada
422 validation	campo obrigatório ausente ou valor inválido
429 rate_limited	limite por minuto do plano excedido

{ "error": { "code": "unauthorized", "message": "Chave de API ausente ou inválida." } }

Módulo

WhatsApp · Conexões

Comece por aqui: descubra os números disponíveis e as capacidades reais de cada conexão antes de enviar.

GET/connections GET/connections/:id GET/connections/:id/health GET/connections/:id/profile PATCH/connections/:id/profile

GET/connectionsEscopo: readOficial + Básico

Lista conexões WhatsApp e capacidades.

Retorna connection_id para automações, sem expor tokens, QR ou credenciais do provider. capabilities é a fonte de verdade: a conexão Oficial (Meta) expõe todos os tipos e ações; a conexão do plano Básico expõe provider "freemium" com apenas text e send.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/connections" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Conexões retornadas.

Exemplo de resposta

{
  "data": [{
    "id": "<CONNECTION_ID>",
    "type": "official",
    "status": "connected",
    "phone_number": "556292498338",
    "capabilities": {
      "provider": "meta_cloud_api",
      "message_types": ["text", "template", "image", "video", "audio", "document", "sticker", "location", "contacts", "interactive", "reaction"],
      "actions": ["send", "mark_read", "media_upload", "media_get", "media_download", "media_delete"]
    }
  }, {
    "id": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
    "type": "freemium",
    "status": "connected",
    "phone_number": "5511988887777",
    "capabilities": {
      "provider": "freemium",
      "message_types": ["text"],
      "actions": ["send"]
    }
  }]
}

GET/connections/:idEscopo: readOficial + Básico

Consulta uma conexão.

Use para confirmar status e tipos de mensagem suportados antes da automação.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	uuid	ID da conexão.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/connections/<CONNECTION_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Conexão retornada.
404	Conexão não encontrada.

GET/connections/:id/healthEscopo: readOficial (Meta)Requer plano Oficial ou Agency

Saúde e limites do número Oficial.

Consulta a Meta em tempo real: qualidade (quality_rating), limite de conversas (messaging_limit_tier), throughput, status de verificação e health_status com o motivo quando o número não pode enviar.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	uuid	ID da conexão Oficial.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/connections/<CONNECTION_ID>/health" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Detalhe retornado direto da Meta.
403	upgrade_required: recurso do plano Oficial/Agency.
422	Conexão não é Oficial.

Exemplo de resposta

{
  "data": {
    "connection_id": "<CONNECTION_ID>",
    "display_phone_number": "+55 62 9249-8338",
    "verified_name": "Zyron Grid",
    "quality_rating": "GREEN",
    "platform_type": "CLOUD_API",
    "code_verification_status": "VERIFIED",
    "messaging_limit_tier": "TIER_1K",
    "throughput": { "level": "STANDARD" },
    "health_status": { "can_send_message": "AVAILABLE", "entities": [] }
  }
}

GET/connections/:id/profileEscopo: readOficial (Meta)Requer plano Oficial ou Agency

Perfil de negócio do número.

Retorna o perfil exibido no WhatsApp: about, endereço, descrição, e-mail, vertical, sites e foto.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	uuid	ID da conexão Oficial.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/connections/<CONNECTION_ID>/profile" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Perfil retornado.
422	Conexão não é Oficial.

Exemplo de resposta

{
  "data": {
    "connection_id": "<CONNECTION_ID>",
    "about": "Atendimento das 8h às 18h",
    "description": "Automação de WhatsApp para operações comerciais.",
    "email": "contato@zyronstack.com",
    "vertical": "PROF_SERVICES",
    "websites": ["https://connect.zyronstack.com"],
    "profile_picture_url": "https://..."
  }
}

PATCH/connections/:id/profileEscopo: writeOficial (Meta)Requer plano Oficial ou Agency

Atualiza o perfil de negócio.

Somente os campos enviados são alterados. about aceita até 139 caracteres; websites aceita até 2 URLs http(s); vertical usa o catálogo da Meta (RETAIL, PROF_SERVICES, HEALTH…).

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	uuid	ID da conexão Oficial.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`about`opcional	string	Texto do perfil (1 a 139 caracteres).
`address`opcional	string	Endereço do negócio (até 256).
`description`opcional	string	Descrição (até 512).
`email`opcional	string	E-mail de contato.
`vertical`opcional	string	Segmento no catálogo da Meta.
`websites`opcional	string[]	Até 2 URLs http(s).

Exemplos prontos

curl -X PATCH "https://connect.zyronstack.com/api/v1/connections/<CONNECTION_ID>/profile" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "about": "Atendimento das 8h às 18h",
  "websites": ["https://connect.zyronstack.com"]
}'

Respostas

200	Perfil atualizado; retorna o estado atual.
422	Campo inválido ou conexão não Oficial.

Módulo

Contatos

Cadastre, consulte e mova contatos dentro do funil do CRM.

GET/contacts GET/contacts/:id POST/contacts PATCH/contacts/:id

GET/contactsEscopo: readOficial + Básico

Lista contatos da conta autenticada.

Use para alimentar CRMs externos, sincronizar bases e buscar contatos por etapa.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Campo	Tipo	Descrição
`stage_id`opcional	uuid	Filtra contatos por uma etapa do funil.
`connection_id`opcional	uuid	Filtra pela conexão WhatsApp dona da identidade.
`phone`opcional	string	Filtra por telefone com DDI (somente dígitos são considerados).
`username`opcional	string	Filtra pelo identificador externo persistido no contato.
`business_scoped_user_id`opcional	string	Filtra pela identidade BSUID recebida da Meta.
`parent_business_scoped_user_id`opcional	string	Filtra pelo parent BSUID recebido da Meta.
`limit`opcional	number	Quantidade de registros por página. Padrão 50; máximo 200 na maioria das listas.
`offset`opcional	number	Índice inicial da página. Use pagination.next_offset para buscar a próxima página.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/contacts?limit=20&offset=0" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Lista retornada com paginação.
401	Chave ausente ou inválida.
403	A chave não possui escopo read.

Exemplo de resposta

{
  "data": [
    {
      "id": "<CONTACT_ID>",
      "name": "Maria Silva",
      "phone": "5511999998888",
      "username": "maria",
      "stage_id": "<STAGE_ID>",
      "created_at": "2026-06-15T12:30:00.000Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 134,
    "next_offset": 20
  }
}

GET/contacts/:idEscopo: readOficial + Básico

Consulta um contato com jornada e vendas.

Retorna dados do contato, sessões de origem Signal e vendas relacionadas às conversas desse contato.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	uuid	ID do contato.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/contacts/<CONTACT_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Contato encontrado.
404	Contato não encontrado nesta conta.

Exemplo de resposta

{
  "data": {
    "id": "<CONTACT_ID>",
    "name": "Maria Silva",
    "phone": "5511999998888",
    "username": "maria",
    "stage_id": "<STAGE_ID>",
    "sessions": [
      {
        "channel": "meta",
        "utm_source": "facebook",
        "utm_campaign": "campanha-principal",
        "ad_id": "23800000000000000",
        "landing_url": "https://sua-pagina.com/oferta"
      }
    ],
    "sales": [
      {
        "id": "91c9fd84-b47f-44ee-9b5e-4e93fc35b912",
        "status": "paid",
        "gross_cents": 19700,
        "currency": "BRL",
        "product_name": "Produto principal"
      }
    ]
  }
}

POST/contactsEscopo: writeOficial + Básico

Cria ou atualiza contato por identidade.

Informe ao menos uma identidade: phone, username, business_scoped_user_id ou parent_business_scoped_user_id. O telefone é normalizado apenas com dígitos. Identidades Meta (username/BSUID) exigem connection_id. Se a identidade já existir, a API atualiza os campos enviados.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`phone`opcional	string	Telefone com DDI, somente números. Obrigatório quando nenhuma outra identidade for enviada.
`connection_id`opcional	uuid	Conexão dona da identidade. Obrigatório com username, BSUID ou parent BSUID.
`name`opcional	string	Nome exibido no CRM, até 120 caracteres.
`username`opcional	string	Identificador externo ou usuário social.
`business_scoped_user_id`opcional	string	BSUID recebido da Meta.
`parent_business_scoped_user_id`opcional	string	Parent BSUID recebido da Meta.
`stage_id`opcional	uuid	Etapa inicial do funil. Precisa pertencer à conta.

Exemplos prontos

curl -X POST "https://connect.zyronstack.com/api/v1/contacts" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "phone": "5511999998888",
  "name": "Joao Silva",
  "username": "joao",
  "stage_id": "<STAGE_ID>"
}'

Respostas

201	Contato criado.
200	Contato existente atualizado.
422	phone ausente ou stage_id inválido.

Exemplo de resposta

{
  "data": {
    "id": "<CONTACT_ID>",
    "name": "Joao Silva",
    "phone": "5511999998888",
    "username": "joao",
    "stage_id": "<STAGE_ID>",
    "created_at": "2026-06-15T12:30:00.000Z"
  },
  "created": true
}

PATCH/contacts/:idEscopo: writeOficial + Básico

Atualiza dados ou move o contato de etapa.

Envie somente os campos que deseja alterar. stage_id é validado contra as etapas da conta. As identidades WhatsApp (phone, BSUID, parent BSUID) também podem ser completadas por aqui.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	uuid	ID do contato.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`name`opcional	string	Novo nome do contato.
`phone`opcional	string	Novo telefone com DDI (somente dígitos).
`username`opcional	string	Novo identificador externo.
`business_scoped_user_id`opcional	string	BSUID recebido da Meta.
`parent_business_scoped_user_id`opcional	string	Parent BSUID recebido da Meta.
`stage_id`opcional	uuid	Nova etapa do funil.

Exemplos prontos

curl -X PATCH "https://connect.zyronstack.com/api/v1/contacts/<CONTACT_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "stage_id": "<STAGE_ID>",
  "name": "Joao Silva"
}'

Respostas

200	Contato atualizado.
404	Contato não encontrado.
422	stage_id não pertence à conta.

Exemplo de resposta

{
  "data": {
    "id": "<CONTACT_ID>",
    "name": "Joao Silva",
    "phone": "5511999998888",
    "username": "joao",
    "stage_id": "<STAGE_ID>",
    "created_at": "2026-06-15T12:30:00.000Z"
  }
}

Módulo

Etapas do funil

Gerencie as colunas do funil usadas no CRM.

GET/stages POST/stages PATCH/stages/:id DELETE/stages/:id

GET/stagesEscopo: readOficial + Básico

Lista etapas ordenadas por posição.

Use antes de mover contatos para descobrir os IDs válidos de etapa.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/stages" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Etapas retornadas.

Exemplo de resposta

{
  "data": [
    {
      "id": "<STAGE_ID>",
      "name": "Negociando",
      "position": 2,
      "color": "#D9982F",
      "auto_kind": null,
      "created_at": "2026-06-15T12:30:00.000Z"
    }
  ]
}

POST/stagesEscopo: writeOficial + Básico

Cria uma nova etapa.

A nova etapa entra após a última posição existente.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`name`obrigatório	string	Nome da etapa, até 40 caracteres.
`color`opcional	string	Cor em hexadecimal. Padrão #5b9bd9.

Exemplos prontos

curl -X POST "https://connect.zyronstack.com/api/v1/stages" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "name": "Negociando",
  "color": "#D9982F"
}'

Respostas

201	Etapa criada.
422	name ausente.

Exemplo de resposta

{
  "data": {
    "id": "<STAGE_ID>",
    "name": "Negociando",
    "position": 2,
    "color": "#D9982F",
    "auto_kind": null,
    "created_at": "2026-06-15T12:30:00.000Z"
  }
}

PATCH/stages/:idEscopo: writeOficial + Básico

Atualiza nome, cor ou posição.

Envie ao menos um campo. A posição é normalizada para número inteiro maior ou igual a zero.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	uuid	ID da etapa.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`name`opcional	string	Novo nome da etapa.
`color`opcional	string	Nova cor hexadecimal.
`position`opcional	number	Nova posição no funil.

Exemplos prontos

curl -X PATCH "https://connect.zyronstack.com/api/v1/stages/<STAGE_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "name": "Proposta enviada",
  "color": "#5B9BD9",
  "position": 3
}'

Respostas

200	Etapa atualizada.
422	Nenhum campo enviado ou nome inválido.

Exemplo de resposta

{
  "data": {
    "id": "<STAGE_ID>",
    "name": "Proposta enviada",
    "position": 3,
    "color": "#5B9BD9",
    "auto_kind": null,
    "created_at": "2026-06-15T12:30:00.000Z"
  }
}

DELETE/stages/:idEscopo: writeOficial + Básico

Remove uma etapa do funil.

A API mantém ao menos uma etapa. Contatos da etapa removida voltam à derivação automática.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	uuid	ID da etapa.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X DELETE "https://connect.zyronstack.com/api/v1/stages/<STAGE_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Etapa removida.
422	Tentativa de remover a última etapa.

Exemplo de resposta

{
  "deleted": true
}

Módulo

Vendas

Consulte vendas atribuídas pelo Signal, com status, produto, valor e origem.

GET/sales

GET/salesEscopo: readOficial + BásicoRequer plano Oficial ou Agency

Lista vendas atribuídas.

Use para dashboards financeiros, auditoria de campanhas e conciliação de vendas. Disponível a partir do plano Oficial (abaixo disso a API responde 403 upgrade_required).

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Campo	Tipo	Descrição
`status`opcional	pending \| paid \| refunded \| chargeback	Filtra por status da venda.
`since`opcional	ISO date-time	Retorna vendas criadas a partir desta data.
`limit`opcional	number	Quantidade de registros por página. Padrão 50; máximo 200 na maioria das listas.
`offset`opcional	number	Índice inicial da página. Use pagination.next_offset para buscar a próxima página.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/sales?status=paid&since=2026-06-01T00:00:00.000Z&limit=20&offset=0" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Vendas retornadas.
403	upgrade_required: o plano atual não inclui a API de vendas.

Exemplo de resposta

{
  "data": [
    {
      "id": "91c9fd84-b47f-44ee-9b5e-4e93fc35b912",
      "source": "meta",
      "provider": "kiwify",
      "status": "paid",
      "gross_cents": 19700,
      "fee_cents": 1200,
      "currency": "BRL",
      "product_name": "Produto principal",
      "product_id": "prod_123",
      "conversation_id": "<CONVERSATION_ID>",
      "created_at": "2026-06-15T12:30:00.000Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 12,
    "next_offset": null
  }
}

Módulo

Conversas

Leia conversas do Inbox e o histórico completo de mensagens.

GET/conversations GET/conversations/:id/messages GET/conversations/resolve GET/conversations/:id PATCH/conversations/:id

GET/conversationsEscopo: readOficial + Básico

Lista conversas do Inbox.

Retorna última mensagem, status, conexão e dados básicos do contato.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Campo	Tipo	Descrição
`connection_id`opcional	uuid	Filtra por conexão de WhatsApp.
`contact_id`opcional	uuid	Filtra pelas conversas de um contato.
`phone`opcional	string	Filtra pelo telefone do contato (com DDI).
`status`opcional	open \| closed \| pending	Filtra por status da conversa.
`limit`opcional	number	Quantidade de registros por página. Padrão 50; máximo 200 na maioria das listas.
`offset`opcional	number	Índice inicial da página. Use pagination.next_offset para buscar a próxima página.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/conversations?status=open&limit=20&offset=0" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Conversas retornadas.

Exemplo de resposta

{
  "data": [
    {
      "id": "<CONVERSATION_ID>",
      "connection_id": "<CONNECTION_ID>",
      "contact_id": "<CONTACT_ID>",
      "status": "open",
      "last_message_text": "Quero saber mais",
      "last_message_at": "2026-06-15T12:30:00.000Z",
      "unread_count": 2,
      "contacts": {
        "name": "Maria Silva",
        "phone": "5511999998888"
      }
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 41,
    "next_offset": 20
  }
}

GET/conversations/:id/messagesEscopo: readOficial + Básico

Lista mensagens de uma conversa.

O limite padrão é 100 e o máximo é 500. A ordenação é crescente por created_at.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	uuid	ID da conversa.

Parâmetros de query

Campo	Tipo	Descrição
`limit`opcional	number	Quantidade de mensagens. Padrão 100; máximo 500.
`offset`opcional	number	Índice inicial da página.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/conversations/<CONVERSATION_ID>/messages?limit=100&offset=0" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Mensagens retornadas.
404	Conversa não encontrada.

Exemplo de resposta

{
  "data": [
    {
      "id": "41a9fa77-6b9d-4d94-a48d-74d036c54121",
      "direction": "in",
      "body": "Quero saber mais",
      "created_at": "2026-06-15T12:30:00.000Z"
    },
    {
      "id": "d38adf37-0f2a-477f-8d8a-238caab12411",
      "direction": "out",
      "body": "Claro, vou te explicar.",
      "created_at": "2026-06-15T12:31:00.000Z"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 2,
    "next_offset": null
  }
}

GET/conversations/resolveEscopo: readOficial + Básico

Resolve uma conversa por número.

Evita depender de UUID prévio: use connection_id + phone, BSUID, parent BSUID ou username. O webhook Zyron já entrega este UUID pronto.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Campo	Tipo	Descrição
`connection_id`obrigatório	uuid	Conexão do WhatsApp.
`phone`opcional	string	Telefone com DDI.
`business_scoped_user_id`opcional	string	Identidade BSUID da Meta.
`parent_business_scoped_user_id`opcional	string	Parent BSUID da Meta.
`username`opcional	string	Usuário externo persistido no contato.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/conversations/resolve?connection_id=<CONNECTION_ID>&phone=5511999998888" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Conversa resolvida.
404	Contato ou conversa não encontrado.

Exemplo de resposta

{
  "data": {
    "id": "<CONVERSATION_ID>",
    "connection_id": "<CONNECTION_ID>",
    "status": "open",
    "last_inbound_at": "2026-07-13T13:28:28.347Z",
    "contact": { "id": "<CONTACT_ID>", "phone": "5511999998888" }
  }
}

GET/conversations/:idEscopo: readOficial + Básico

Detalhe operacional da conversa.

Retorna status, tags, atendente, nota interna, last_inbound_at (janela de 24h) e identidades do contato.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	uuid	ID da conversa.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/conversations/<CONVERSATION_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Conversa retornada.
404	Conversa não encontrada.

PATCH/conversations/:idEscopo: writeOficial + Básico

Atualiza estado operacional da conversa.

Fecha, reabre, deixa pendente, atribui atendente e atualiza tags/notas internas.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	uuid	ID da conversa.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`status`opcional	open \| closed \| pending	Estado da conversa.
`tags`opcional	string[]	Etiquetas operacionais (até 30).
`assignee_name`opcional	string	Atendente responsável.
`internal_note`opcional	string	Nota interna da equipe, até 4000 caracteres.

Exemplos prontos

curl -X PATCH "https://connect.zyronstack.com/api/v1/conversations/<CONVERSATION_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "status": "pending",
  "tags": ["lead-quente", "n8n"],
  "assignee_name": "Time comercial"
}'

Respostas

200	Conversa atualizada.

Módulo

Mensageria

API WhatsApp unificada: envie, acompanhe, marque como lido e consulte texto, template, mídia, localização, contatos, interativos e reações.

POST/messages POST/messages POST/messages POST/messages POST/messages GET/messages GET/messages/:id POST/messages/:id/read

POST/messagesEscopo: writeOficial + Básico

Envia uma mensagem WhatsApp tipada.

Para responder use conversation_id; para iniciar use connection_id + recipient. Recipient aceita telefone, contato, BSUID, parent BSUID ou username e nunca é inferido. type padrão é text — o único tipo aceito pela conexão do plano Básico; os demais tipos exigem conexão Oficial e plano Oficial/Agency.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`text`opcional	string	Texto da mensagem; obrigatório quando type=text.
`type`opcional	text \| template \| image \| video \| audio \| document \| sticker \| location \| contacts \| interactive \| reaction	Tipo de mensagem. Padrão text.
`template`opcional	object	Para template: name, language e components opcionais.
`media`opcional	object	Para mídia: link ou id; caption e filename são opcionais.
`interactive`opcional	object	Objeto interativo nativo da Meta (button, list ou flow).
`reply_to_message_id`opcional	string	WAMID da mensagem que será respondida.
`biz_opaque_callback_data`opcional	string	Correlação devolvida pela Meta nos status (máximo 512).
`conversation_id`opcional	uuid	Use para responder uma conversa existente.
`connection_id`opcional	uuid	Conexão usada para iniciar uma nova conversa.
`recipient`opcional	object	Para iniciar: phone, contact_id, business_scoped_user_id, parent_business_scoped_user_id ou username.
`to`opcional	string	Legado: equivalente a recipient.phone.

Exemplos prontos

curl -X POST "https://connect.zyronstack.com/api/v1/messages" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "conversation_id": "<CONVERSATION_ID>",
  "type": "text",
  "text": "Ola, Maria. Posso te ajudar?"
}'

Respostas

202	Meta aceitou o envio; acompanhe delivery_status no histórico ou webhook.
404	Conversa ou conexão não encontrada.
422	text ausente ou destino incompleto.

Exemplo de resposta

{
  "data": {
    "conversation_id": "<CONVERSATION_ID>",
    "provider_message_id": "wamid.HBgM...",
    "type": "text",
    "recipient": { "phone": "5511999998888", "business_scoped_user_id": "BR.4389531741319467" },
    "accepted": true,
    "delivery_status": "pending"
  }
}

POST/messagesEscopo: writeOficial (Meta)Requer plano Oficial ou Agency

Envia imagem, vídeo, documento ou figurinha.

Envie media.id retornado por POST /media ou media.link público. O bloco Mídia explica upload e download.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`connection_id`obrigatório	uuid	Número Oficial que envia.
`recipient.phone`obrigatório	string	Telefone com DDI.
`type`obrigatório	image \| video \| document \| sticker	Tipo do arquivo.
`media.id`opcional	string	ID de POST /media; prefira a ele.
`media.link`opcional	URL	Alternativa pública ao media.id.

Exemplos prontos

curl -X POST "https://connect.zyronstack.com/api/v1/messages" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "connection_id": "<CONNECTION_ID>",
  "recipient": { "phone": "<TELEFONE_COM_DDI>" },
  "type": "image",
  "media": { "id": "<MEDIA_ID>", "caption": "Proposta em anexo" }
}'

Respostas

202	Arquivo aceito; acompanhe pelo wamid.

POST/messagesEscopo: writeOficial (Meta)Requer plano Oficial ou Agency

Envia áudio ou mensagem de voz.

Faça upload antes e use media.id. Áudio não recebe legenda.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`media.id`obrigatório	string	ID retornado pelo upload.

Exemplos prontos

curl -X POST "https://connect.zyronstack.com/api/v1/messages" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "connection_id": "<CONNECTION_ID>",
  "recipient": { "phone": "<TELEFONE_COM_DDI>" },
  "type": "audio",
  "media": { "id": "<MEDIA_ID>" }
}'

Respostas

202	Áudio aceito.

POST/messagesEscopo: writeOficial (Meta)Requer plano Oficial ou Agency

Envia template aprovado pela Meta.

Use para iniciar conversa fora da janela de 24 h; consulte GET /templates antes.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`template.name`obrigatório	string	Nome exato aprovado na Meta.
`template.components`opcional	array	Parâmetros do template.

Exemplos prontos

curl -X POST "https://connect.zyronstack.com/api/v1/messages" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "connection_id": "<CONNECTION_ID>",
  "recipient": { "phone": "<TELEFONE_COM_DDI>" },
  "type": "template",
  "template": { "name": "NOME_DO_TEMPLATE", "language": "pt_BR", "components": [] }
}'

Respostas

202	Template aceito.

POST/messagesEscopo: writeOficial (Meta)Requer plano Oficial ou Agency

Envia botões, lista, localização, contatos ou reação.

Troque type e seu objeto: interactive, location, contacts ou reaction. Os objetos nativos são preservados.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`interactive \| location \| contacts \| reaction`opcional	object	Conteúdo nativo do tipo escolhido.

Exemplos prontos

curl -X POST "https://connect.zyronstack.com/api/v1/messages" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "conversation_id": "<CONVERSATION_ID>",
  "type": "location",
  "location": { "latitude": -22.879, "longitude": -43.104, "name": "Local do atendimento" }
}'

Respostas

202	Mensagem especial aceita.

GET/messagesEscopo: readOficial + Básico

Lista mensagens e estados do provider.

Filtre por connection_id, conversation_id, contact_id, direction, status ou provider_message_id (WAMID).

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Campo	Tipo	Descrição
`connection_id`opcional	uuid	Conexão WhatsApp.
`conversation_id`opcional	uuid	Conversa interna.
`provider_message_id`opcional	string	WAMID/ID retornado pelo provider.
`limit`opcional	number	Quantidade de registros por página. Padrão 50; máximo 200 na maioria das listas.
`offset`opcional	number	Índice inicial da página. Use pagination.next_offset para buscar a próxima página.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/messages?connection_id=<CONNECTION_ID>&provider_message_id=wamid.HBgM..." \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Mensagens paginadas.

GET/messages/:idEscopo: readOficial + Básico

Consulta uma mensagem com payload do provider.

Use para ler metadados de mídia, interativos e eventos recebidos sem perder o payload original.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	integer	ID interno do log.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/messages/42" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Mensagem retornada.

POST/messages/:id/readEscopo: writeOficial (Meta)

Marca uma mensagem inbound como lida.

Disponível para conexão Oficial; usa o WAMID salvo no histórico.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	integer	ID interno do log inbound.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X POST "https://connect.zyronstack.com/api/v1/messages/42/read" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Leitura confirmada.
422	Tipo de conexão não suporta leitura.

Módulo

WhatsApp · Mídia

Fluxo completo de arquivo: envie para a Meta, use o media_id em uma mensagem, consulte metadados e baixe mídia recebida sem expor o token da conexão.

POST/media GET/media/:id GET/media/:id/download DELETE/media/:id

POST/mediaEscopo: writeOficial (Meta)Requer plano Oficial ou Agency

Faz upload de arquivo para a Meta.

Envie multipart/form-data com connection_id e file. A resposta contém media_id para usar em POST /messages.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`connection_id`obrigatório	uuid	Conexão Oficial dona do arquivo.
`file`obrigatório	binary	Arquivo até 100 MB. O limite final também depende do formato aceito pela Meta.

Exemplos prontos

curl -X POST "https://connect.zyronstack.com/api/v1/media" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -F "connection_id=<CONNECTION_ID>" \
  -F "file=@/CAMINHO/arquivo.pdf"

Respostas

201	Upload concluído; use data.id como media.id.

GET/media/:idEscopo: readOficial (Meta)Requer plano Oficial ou Agency

Consulta metadados e rota de download.

Use o media_id do payload da mensagem. A resposta devolve mime_type, tamanho, hash e uma download_url autenticada do Zyron.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	string	media_id da Meta.

Parâmetros de query

Campo	Tipo	Descrição
`connection_id`obrigatório	uuid	Conexão dona da mídia.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/media/<MEDIA_ID>?connection_id=<CONNECTION_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Metadados retornados.

Exemplo de resposta

{
  "data": {
    "id": "<MEDIA_ID>",
    "mime_type": "image/jpeg",
    "file_size": "303833",
    "download_url": "https://connect.zyronstack.com/api/v1/media/<MEDIA_ID>/download?connection_id=<CONNECTION_ID>",
    "download_requires_authorization": true
  }
}

GET/media/:id/downloadEscopo: readOficial (Meta)Requer plano Oficial ou Agency

Baixa o arquivo recebido ou enviado.

Use a mesma chave Bearer; a API transmite o binário e nunca devolve o token Meta. Funciona para image, audio, video, document e sticker oficiais.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	string	media_id da Meta.

Parâmetros de query

Campo	Tipo	Descrição
`connection_id`obrigatório	uuid	Conexão dona da mídia.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/media/<MEDIA_ID>/download?connection_id=<CONNECTION_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Binário da mídia no content-type original.

DELETE/media/:idEscopo: writeOficial (Meta)Requer plano Oficial ou Agency

Remove mídia armazenada na Meta.

Remova somente mídias que não serão mais usadas por mensagens ou automações.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	string	media_id da Meta.

Parâmetros de query

Campo	Tipo	Descrição
`connection_id`obrigatório	uuid	Conexão dona da mídia.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X DELETE "https://connect.zyronstack.com/api/v1/media/<MEDIA_ID>?connection_id=<CONNECTION_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Mídia removida.

Módulo

Templates

Catálogo local de modelos, sincronizado com o status de aprovação da Meta.

GET/templates

GET/templatesEscopo: readOficial (Meta)

Lista templates da conta.

Use para descobrir nome, categoria, idioma e status antes de enviar um template pela mensageria.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Campo	Tipo	Descrição
`status`opcional	draft \| pending \| approved \| rejected	Filtra por status de aprovação.
`limit`opcional	number	Quantidade de registros por página. Padrão 50; máximo 200 na maioria das listas.
`offset`opcional	number	Índice inicial da página. Use pagination.next_offset para buscar a próxima página.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/templates?status=approved&limit=20&offset=0" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Templates retornados.

Exemplo de resposta

{
  "data": [
    {
      "id": "b2d0f4a1-3c55-4c7e-9a1b-6f2d8e0a1c34",
      "name": "boas_vindas",
      "meta_template_name": "boas_vindas",
      "category": "MARKETING",
      "language": "pt_BR",
      "status": "approved",
      "variables": ["nome"],
      "updated_at": "2026-06-15T12:30:00.000Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 8, "next_offset": null }
}

Módulo

Webhooks de saída

Configure para onde o Connect envia os eventos da sua conexão. Entrega com assinatura HMAC (x-zyron-signature), retry com backoff e dead-letter; eventos estruturados whatsapp.message.received|sent|delivered|read|failed e whatsapp.connection.updated.

GET/webhooks PUT/webhooks DELETE/webhooks GET/webhooks/deliveries

GET/webhooksEscopo: readOficial + Básico

Lista as configurações de webhook.

Uma configuração por conexão. O secret é retornado ao dono da chave — é ele que valida a assinatura x-zyron-signature na ponta. structured_events lista o catálogo de eventos v2.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Campo	Tipo	Descrição
`connection_id`opcional	uuid	Filtra por conexão.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/webhooks?connection_id=<CONNECTION_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Configurações retornadas.

Exemplo de resposta

{
  "data": [
    {
      "id": "5f0d5a44-1187-4f1e-a2b0-1d40c07b0e10",
      "connection_id": "<CONNECTION_ID>",
      "url": "https://seu-n8n.com/webhook/zyron",
      "events": ["whatsapp.message.received", "whatsapp.message.failed"],
      "secret": "zwh_9f2c...",
      "active": true
    }
  ],
  "structured_events": [
    "whatsapp.message.received",
    "whatsapp.message.sent",
    "whatsapp.message.delivered",
    "whatsapp.message.read",
    "whatsapp.message.failed",
    "whatsapp.connection.updated"
  ]
}

PUT/webhooksEscopo: writeOficial + Básico

Cria ou atualiza o webhook de uma conexão.

events vazio assina todos os eventos. Aceita os eventos estruturados v2 e os nomes nativos do provider (compatibilidade). Sem secret no corpo, o Connect mantém o atual ou gera um novo zwh_.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`connection_id`obrigatório	uuid	Conexão dona do webhook.
`url`obrigatório	URL	Endpoint http(s) que recebe os eventos.
`events`opcional	string[]	Eventos assinados. Vazio = todos.
`secret`opcional	string	Segredo do HMAC. Opcional; gerado quando ausente.
`active`opcional	boolean	Padrão true. false pausa as entregas.

Exemplos prontos

curl -X PUT "https://connect.zyronstack.com/api/v1/webhooks" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "connection_id": "<CONNECTION_ID>",
  "url": "https://seu-n8n.com/webhook/zyron",
  "events": ["whatsapp.message.received", "whatsapp.message.failed"]
}'

Respostas

201	Webhook criado.
200	Webhook atualizado.
422	URL inválida ou evento não suportado pela conexão.

DELETE/webhooksEscopo: writeOficial + Básico

Desativa o webhook de uma conexão.

Pausa as entregas mantendo configuração e histórico para auditoria. Reative com PUT { active: true }.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Campo	Tipo	Descrição
`connection_id`obrigatório	uuid	Conexão do webhook.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X DELETE "https://connect.zyronstack.com/api/v1/webhooks?connection_id=<CONNECTION_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Webhook desativado.
404	Nenhum webhook configurado.

GET/webhooks/deliveriesEscopo: readOficial + Básico

Histórico de entregas do webhook.

Cada entrega mostra evento, status (pending, delivered, failed, dead), tentativas, último HTTP status e erro. Use para depurar a sua ponta sem abrir o painel.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Campo	Tipo	Descrição
`connection_id`opcional	uuid	Filtra por conexão.
`status`opcional	pending \| delivered \| failed \| dead	Filtra pelo estado da entrega.
`event`opcional	string	Filtra pelo nome do evento entregue.
`limit`opcional	number	Quantidade de registros por página. Padrão 50; máximo 200 na maioria das listas.
`offset`opcional	number	Índice inicial da página. Use pagination.next_offset para buscar a próxima página.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/webhooks/deliveries?connection_id=<CONNECTION_ID>&status=failed" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Entregas retornadas.

Exemplo de resposta

{
  "data": [
    {
      "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "connection_id": "<CONNECTION_ID>",
      "event": "whatsapp.message.received",
      "status": "delivered",
      "attempts": 1,
      "last_status": 200,
      "last_error": null,
      "target_url": "https://seu-n8n.com/webhook/zyron",
      "delivered_at": "2026-07-14T13:28:29.120Z",
      "created_at": "2026-07-14T13:28:27.898Z"
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "total": 1, "next_offset": null }
}

Módulo

Eventos de webhook

Auditoria dos eventos recebidos dos providers, com o payload nativo preservado.

GET/webhook-events

GET/webhook-eventsEscopo: readOficial + Básico

Lista eventos recebidos.

Retorna os eventos brutos (mensagens, status, QR) recebidos das conexões, para auditoria e reprocessamento externo.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Campo	Tipo	Descrição
`connection_id`opcional	uuid	Filtra por conexão.
`source`opcional	meta \| freemium	Filtra pela origem do evento: conexão Oficial (meta) ou conexão do plano Básico (freemium).
`event`opcional	string	Filtra por nome do evento (ex.: messages).
`limit`opcional	number	Quantidade de registros por página. Padrão 50; máximo 200 na maioria das listas.
`offset`opcional	number	Índice inicial da página. Use pagination.next_offset para buscar a próxima página.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/webhook-events?source=meta&limit=20&offset=0" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Eventos retornados.

Exemplo de resposta

{
  "data": [
    {
      "id": 30,
      "source": "meta",
      "event": "messages",
      "connection_id": "<CONNECTION_ID>",
      "payload": { "messages": [{ "from": "5511999998888", "type": "text" }] },
      "created_at": "2026-07-13T13:28:27.898Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 2, "next_offset": null }
}