Esses eventos monitoram a saúde dos seus canais de comunicação — WhatsApp, Instagram, widget, Telegram e outros. Use-os para reagir automaticamente a desconexões, alertar a equipe técnica e evitar que clientes fiquem sem resposta por causa de um canal caído.
Lista de eventos
| Evento | Quando dispara |
|---|
channel.connected | Um canal é conectado com sucesso ao workspace |
channel.disconnected | Um canal perde a conexão |
channel.error | O canal apresenta erro recorrente sem se desconectar completamente |
channel.connected
Quando dispara
Um canal é conectado com sucesso — seja na primeira configuração, seja reconectado após uma desconexão. Para WhatsApp via QR Code, dispara no momento em que o scan é concluído. Para WABA, dispara após a verificação do webhook pela Meta.
Payload
{
"event": "channel.connected",
"event_id": "evt_01HX8A1K9MFQR4YZDNV7P9WCE",
"timestamp": "2026-04-19T10:00:00Z",
"workspace_id": "ws_abc123",
"data": {
"channel_id": "chan_789",
"channel_type": "whatsapp",
"channel_name": "Suporte WhatsApp",
"phone_number": "+5547988543326",
"provider": "waba",
"status": "connected",
"connected_by": "usr_321",
"connected_at": "2026-04-19T10:00:00Z"
}
}
Campos principais
| Campo | Tipo | Descrição |
|---|
channel_id | string | ID único do canal |
channel_type | enum | whatsapp, instagram, widget, telegram, slack |
channel_name | string | Nome dado ao canal no workspace |
phone_number | string | null | Número do canal (para canais de telefonia) |
provider | string | null | Provedor específico: waba, qrcode, meta_ig, etc. |
status | enum | Sempre connected nesse evento |
connected_by | string | null | ID do usuário que realizou a conexão |
connected_at | string | Timestamp ISO 8601 da conexão |
Exemplo de uso
Use channel.connected para atualizar o status operacional no seu painel interno e notificar a equipe quando um canal estratégico voltar a funcionar após manutenção.
channel.disconnected
Quando dispara
Um canal perde a conexão com a plataforma. Para WhatsApp via QR Code, isso acontece quando o celular fica sem internet ou o WhatsApp Web é desconectado de outro lugar. Para WABA e Instagram, acontece quando as credenciais expiram ou o token é revogado.
Payload
{
"event": "channel.disconnected",
"event_id": "evt_01HX8B3M2PGTS6YADOV8Q1XDF",
"timestamp": "2026-04-19T23:15:00Z",
"workspace_id": "ws_abc123",
"data": {
"channel_id": "chan_789",
"channel_type": "whatsapp",
"channel_name": "Suporte WhatsApp",
"phone_number": "+5547988543326",
"provider": "waba",
"status": "disconnected",
"disconnection_reason": "token_expired",
"last_active_at": "2026-04-19T23:14:30Z",
"disconnected_at": "2026-04-19T23:15:00Z"
}
}
Campos principais
| Campo | Tipo | Descrição |
|---|
status | enum | Sempre disconnected nesse evento |
disconnection_reason | enum | token_expired, revoked, phone_offline, session_conflict, unknown |
last_active_at | string | Última vez que o canal estava operacional |
disconnected_at | string | Timestamp ISO 8601 da desconexão |
Exemplo de uso
Configure alertas críticos para channel.disconnected — mensagens enviadas por contatos enquanto o canal está desconectado ficam enfileiradas, mas você não pode responder. Reconecte o canal o quanto antes pelo dashboard em Canais.
Para WhatsApp via QR Code, disconnection_reason: "phone_offline" é o mais comum. Considere migrar para WABA (WhatsApp Business API oficial) para evitar dependência do celular ficar ligado.
channel.error
Quando dispara
O canal apresenta erros recorrentes mas ainda não perdeu a conexão completamente — por exemplo, falhas intermitentes de envio de mensagens, rate limits do canal sendo atingidos ou latência anormalmente alta. Esse evento é mais informativo que crítico, mas merece atenção.
Payload
{
"event": "channel.error",
"event_id": "evt_01HX8C5P4RHTW7ZBEPV9S2YEG",
"timestamp": "2026-04-19T22:05:00Z",
"workspace_id": "ws_abc123",
"data": {
"channel_id": "chan_789",
"channel_type": "whatsapp",
"channel_name": "Suporte WhatsApp",
"phone_number": "+5547988543326",
"provider": "waba",
"status": "degraded",
"error_code": "131056",
"error_message": "Too many messages sent from this phone number in a short time",
"error_category": "rate_limit",
"affected_message_ids": [
"msg_01HX8C01",
"msg_01HX8C02",
"msg_01HX8C03"
],
"occurred_at": "2026-04-19T22:05:00Z"
}
}
Campos principais
| Campo | Tipo | Descrição |
|---|
status | enum | degraded — o canal está com problemas mas ainda conectado |
error_code | string | Código de erro retornado pelo canal ou provedor |
error_message | string | Descrição legível do erro |
error_category | enum | rate_limit, auth_error, provider_error, network_error, unknown |
affected_message_ids | array | IDs das mensagens impactadas pelo erro (pode ser vazio) |
occurred_at | string | Timestamp ISO 8601 da ocorrência |
Exemplo de uso
Use error_category: "rate_limit" como sinal para ajustar o volume de disparos de broadcasts. Rate limits do WhatsApp Business API aumentam gradualmente conforme a reputação do número — não force o limite ou o número pode ser banido.
Se você receber channel.error com error_category: "auth_error" seguido em breve de channel.disconnected, o token do canal expirou. Vá em Canais no dashboard e reconecte o canal com as credenciais atualizadas.
