Canais

Um canal representa um número WhatsApp conectado ao Coexy. Após criar um canal, compartilhe o connect_url para que o responsável pelo número faça a conexão via WhatsApp Embedded Signup. A página do connect_url mostra a logo, o nome e a cor configurados em Configurações › Organização.

Tipo Channel

type Channel = {
  id:                   string        // UUID
  name:                 string
  status:               'pending' | 'active' | 'disconnected' | 'suspended'
  channel_type:         'whatsapp'
  display_phone_number: string | null // ex: "+55 11 99999-9999"
  phone_number_id:      string | null // ID do número na Meta: {phone_number_id} no meta-proxy para enviar mensagens
  waba_id:              string | null // ID da conta WhatsApp Business: {waba_id} no meta-proxy para templates
  channel_token:        string        // Bearer token do meta-proxy (Authorization: Bearer). Secreto
  channel_token_expires_at: string | null // ISO 8601; null = nunca expira
  connect_url:          string        // link de conexão do número. Não contém o channel_token
  connected_at:         string | null // ISO 8601
  created_at:           string        // ISO 8601
  verification: {
    status:             'not_verified' | 'pending' | 'verified' | 'rejected' | 'failed'
    attempts:           number        // tentativas realizadas
    max_attempts:       number        // limite (sempre 3)
    rejection_reasons:  string[] | null
    verified_at:        string | null // ISO 8601
    url:                string | null // URL pública do wizard de verificação
  }
  payment: {
    configured:         boolean | null // forma de pagamento da Meta configurada na conta WhatsApp Business
    currency:           string | null  // moeda da conta, ex: "BRL"
  }
  coexistence: {
    enabled:                    boolean       // número conectado pelo app WhatsApp Business
    contacts_sync_requested_at: string | null // quando a sincronização de contatos foi pedida
    history_sync_requested_at:  string | null // quando a sincronização do histórico foi pedida
    sync_deadline:              string | null // prazo da Meta para pedir (conexão + 24h)
  }
}

Status do canal

Status	Significado
`pending`	Canal criado, aguardando a conexão do número WhatsApp pelo `connect_url`
`active`	Conectado e funcionando. Os tokens da Meta são renovados automaticamente pelo Coexy
`disconnected`	Acesso revogado pela Meta (ex.: mudança de senha, remoção de permissão) ou canal desconectado no painel. Reconecte pelo `connect_url`
`suspended`	Suspenso administrativamente pelo Coexy

Para ser avisado das mudanças sem consultar a API, assine o evento de webhook channel_status_update.

Tokens são gerenciados automaticamente pelo Coexy. Depois de conectar o WhatsApp, você não precisa renovar tokens. Em casos raros (ex.: revogação de permissão na Meta), o canal muda para disconnected e você reconecta pelo mesmo connect_url, sem recriar o canal.

Token do canal

O channel_token autoriza o envio pelo meta-proxy. Ele é secreto: guarde no seu servidor e nunca coloque em URL. O connect_url usa outro valor, que só serve para conectar o número, então pode ser enviado ao dono do número sem expor o token.

Validade: escolha na criação com token_expires_in_days (1, 7, 30, 90 ou null para nunca expirar). Sem o campo, o token nunca expira. A data fica em channel_token_expires_at.
Token vencido: o meta-proxy responde 401 com "code": "token_expired". Gere outro com POST /channels/:id/rotate-token ou no painel, na aba Configurações do canal.
Vazamento: gere um novo token. O anterior para de funcionar na hora.

Fluxo de conexão

Crie o canal com POST /channels. Ele nasce com status pending.
Compartilhe o connect_url com o dono do número WhatsApp.
O dono abre o link e autoriza pelo WhatsApp Embedded Signup.
O canal muda para active e phone_number_id, waba_id e display_phone_number são preenchidos.

phone_number_id e waba_id só ficam disponíveis após a conexão. Antes disso, são null.

Verificação de Empresa

Cada canal inclui um objeto verification com o status da verificação de empresa junto à Meta. A verificação desbloqueia:

Alcance de até 100K contatos/dia (vs 250 sem verificação)
Até 20 números por Business Manager (vs 2)
Nome da empresa visível nas conversas do WhatsApp
Elegibilidade para selo azul verificado

Compartilhe a verification.url para que o responsável pela empresa envie os documentos de verificação. O processo leva aproximadamente 5 minutos após o envio.

Endpoints

Listar canais

string

required

Sua API Key

GET /channels

curl https://api.coexy.com.br/functions/v1/api/channels \
  -H "x-api-key: crt_pk_sua-chave"

Resposta: Channel[]

Criar canal

POST /channels

string

required

Nome identificador do canal

number | null

Validade do channel_token em dias: 1, 7, 30 ou 90. Ausente ou null: nunca expira.

curl -X POST https://api.coexy.com.br/functions/v1/api/channels \
  -H "x-api-key: crt_pk_sua-chave" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Suporte Principal", "token_expires_in_days": 90 }'

Resposta: Channel — status 201 Created Após criar, compartilhe o connect_url retornado para que o número seja conectado.

Redirecionamento após a conexão

Opcional. Em Configurações › Organização › Redirecionamento após conexão, informe uma URL https://. Assim que o número for conectado pelo connect_url, a pessoa é levada para essa URL com os dados do canal:

https://seusite.com.br/whatsapp-conectado?channel_id=3f1c...&status=connected&phone=5511999999999

Parâmetro	Descrição
`channel_id`	`id` do canal conectado
`status`	Sempre `connected`
`phone`	Número conectado, só dígitos. Ausente se a Meta não informar

Parâmetros que a sua URL já tiver são mantidos. Sem URL configurada, o link mostra a tela de conexão concluída. Use o channel_id para consultar o canal pela API ou aguarde o evento de webhook channel_status_update antes de liberar o envio.

Buscar canal

GET /channels/:id

curl https://api.coexy.com.br/functions/v1/api/channels/uuid-do-canal \
  -H "x-api-key: crt_pk_sua-chave"

Resposta: Channel

Gerar novo token

POST /channels/:id/rotate-token

Gera um novo channel_token. O anterior para de funcionar na hora.

number | null

Validade do novo token em dias: 1, 7, 30 ou 90. Ausente ou null: nunca expira.

boolean

true gera também um novo connect_url. Os links de conexão já enviados deixam de funcionar.

curl -X POST https://api.coexy.com.br/functions/v1/api/channels/uuid-do-canal/rotate-token \
  -H "x-api-key: crt_pk_sua-chave" \
  -H "Content-Type: application/json" \
  -d '{ "token_expires_in_days": 30 }'

Resposta: Channel, com o novo channel_token e channel_token_expires_at

Deletar canal

DELETE /channels/:id

boolean

Obrigatório se o canal está com status: active. Use ?force=true para confirmar.

curl -X DELETE "https://api.coexy.com.br/functions/v1/api/channels/uuid-do-canal?force=true" \
  -H "x-api-key: crt_pk_sua-chave"

Resposta: 204 No Content

Erros

Status	Mensagem	Causa
`403`	`trial_channel_limit`	No período de teste a org já tem 3 canais (`POST /channels`). Assine um plano para criar mais
`404`	`Channel not found`	ID não existe ou não pertence à sua org
`409`	`Channel is active. Use ?force=true...`	Tentou deletar canal ativo sem `?force=true`
`422`	`"name" is required`	Body sem o campo `name`
`422`	`"token_expires_in_days" must be 1, 7, 30, 90 or null`	Validade fora das opções

Introdução

Configurar (Canais & Webhooks)

Enviar Mensagens

WhatsApp Flows

Receber Eventos

Tipo Channel

Status do canal

Token do canal

Fluxo de conexão

Verificação de Empresa

Endpoints

Listar canais

Criar canal

Redirecionamento após a conexão

Buscar canal

Gerar novo token

Deletar canal

Erros