# Conectar a inbox Uma inbox é uma conta ligada à Orkesio: um número de WhatsApp, uma conta profissional do [Instagram](#instagram-e-messenger), uma Página do Facebook ([Messenger](#instagram-e-messenger)) ou um bot do [Telegram](#telegram). O WhatsApp conecta de um destes dois jeitos, escolhidos uma vez: | | WhatsApp Web | API oficial | |---|---|---| | Como liga | QR code ou código de pareamento, pelo celular | Credenciais do seu app na Meta ou da Kapso | | O celular | continua com o WhatsApp, e a inbox é um aparelho conectado | o número sai do app (ou fica nos dois, pela [coexistência](#api-oficial-pela-kapso)) | | Recursos | todos: grupos, status, agenda, enquetes... | os da Meta, mais modelos (`template`) | | Custo por mensagem | nenhum | o da Meta, cobrado por ela | | Tempo para ligar | 1 minuto | de 10 a 30 minutos na primeira vez | O que muda de um para o outro está em [O que funciona em cada canal](/docs/canais). Depois de ligada, a inbox usa as mesmas rotas e os mesmos eventos nos dois casos. ## Criar a inbox Com o token de administrador (header `admintoken`), [`POST /inbox/create`](/endpoint/post/inbox~create): ```json { "name": "loja-centro" } ``` A resposta traz o `token` da inbox: guarde-o. Ele autentica todas as rotas dela (header `token`), inclusive as de conexão abaixo. A inbox nasce `disconnected`. ## WhatsApp Web: QR code ou código 1. Chame [`POST /inbox/connect`](/endpoint/post/inbox~connect) com o token da inbox. - **Sem corpo:** a resposta traz a inbox em `connecting`, com `reason: qr` e o QR code em `qr_code` (imagem PNG em base64). No celular: WhatsApp → **Aparelhos conectados** → **Conectar um aparelho**, e leia o QR code. - **Com `{"phone": "5511999999999"}`:** a resposta traz `reason: pair_code` e um código em `pair_code`. No celular: **Conectar um aparelho** → **Conectar com número de telefone**, e digite o código. O QR code continua vindo em `qr_code`: vale o que for usado primeiro. 2. O QR code muda a cada poucos segundos. Mostre sempre o mais novo, buscando [`GET /inbox/status`](/endpoint/get/inbox~status). Não repita o `connect` enquanto conecta. 3. Quando o celular confirmar, `status` vira `connected` e chega o evento [`inbox.status`](/webhook/inbox.status) com `connected`. O histórico de conversas chega em seguida, aos poucos (`history_days` no `connect` escolhe quantos dias, até 365). Para desligar, [`POST /inbox/disconnect`](/endpoint/post/inbox~disconnect). A inbox sai dos aparelhos conectados do celular; para ligar de novo, leia um QR code novo. ## API oficial A API oficial do WhatsApp (Cloud API, da Meta) liga um número sem QR code: a Meta entrega as mensagens para a Orkesio. Hoje há dois caminhos: | | Com o seu app na Meta | Pela Kapso | |---|---|---| | O que é | Você cria um app na Meta e liga a Orkesio direto nela | A [Kapso](https://kapso.ai), um provedor da Meta, faz o cadastro; a Orkesio fala com ela no lugar da Meta | | O número | só na API: sai do app do celular | só na API, ou **no app e na API ao mesmo tempo** (coexistência) | | Tempo | uns 30 minutos na primeira vez | uns 10 minutos | | Custo além da Meta | nenhum | o plano da Kapso (tem plano grátis para um número) | **Estamos virando provedor de tecnologia (Tech Provider) da Meta.** Quando sair, ligar a API oficial vai ser um botão no painel da Orkesio, com coexistência, sem criar app nem conta em outro lugar. As inboxes ligadas pelos caminhos abaixo continuam funcionando. ## API oficial com o seu app na Meta Não precisa de App Review para os seus números, e a Meta cobra as mensagens direto de você. Neste caminho o número fica **só na API**: para seguir usando o app WhatsApp Business no mesmo número, use a [coexistência pela Kapso](#api-oficial-pela-kapso). ### Antes de começar - Um **portfólio empresarial** na Meta ([business.facebook.com](https://business.facebook.com)). - Um **número só para a API**: novo, ou apagado do app do WhatsApp antes (sem coexistência neste caminho). - Uma **forma de pagamento** na conta do WhatsApp na Meta, para enviar modelos (`template`). - Uma **inbox nova** ([acima](#criar-a-inbox)), nunca conectada pelo QR code. Uma inbox já pareada pelo WhatsApp Web responde `409`: crie outra. ### 1. Criar o app na Meta 1. Em [developers.facebook.com/apps](https://developers.facebook.com/apps), crie um app do tipo **Business** (Empresa) ligado ao seu portfólio. 2. Adicione o produto **WhatsApp**. A Meta cria uma conta do WhatsApp Business (WABA) e um número de teste. 3. Em **WhatsApp → Configuração da API**, adicione o seu número e confirme pelo código por SMS ou ligação. 4. Anote o **ID do número** (`phone_number_id`) e o **ID da conta do WhatsApp Business** (`waba_id`), que aparecem na mesma tela. 5. Em **Configurações do app → Básico**, anote a **Chave secreta do app** (`app_secret`). Preencha também a URL da política de privacidade: ela é obrigatória para publicar o app (passo 4). ### 2. Gerar um token permanente O token temporário da tela de configuração expira em 24 horas. Para a Orkesio, use o token de um usuário do sistema: 1. Em **Configurações do negócio → Usuários → Usuários do sistema**, crie um usuário do sistema com função **Administrador**. 2. Em **Atribuir ativos**, dê a ele o app e a conta do WhatsApp, com controle total. 3. Em **Gerar token**, escolha o app, validade **Nunca** e as permissões `whatsapp_business_messaging` e `whatsapp_business_management`. 4. Guarde o token: a Meta só mostra uma vez. ### 3. Ligar a inbox Com o token da inbox (header `token`), chame [`POST /inbox/cloud`](/endpoint/post/inbox~cloud): ```bash curl -X POST https:///inbox/cloud \ -H "token: " \ -H "Content-Type: application/json" \ -d '{ "phone_number_id": "1375523705642891", "token": "", "waba_id": "102692966164644", "app_secret": "" }' ``` A Orkesio confere o token na Meta, grava o número como dono da inbox e tenta apontar o webhook do número para ela: ```json { "inbox": { "id": "r183e2ef9597845", "name": "loja", "status": "connected", "channel": "whatsapp_cloud", "phone": "5511999999999", "profile_name": "Minha Empresa" }, "webhook_url": "https:///channel/webhook/9f2c...", "verify_token": "9f2c...", "webhook_configured": true } ``` - **Guarde `webhook_url` e `verify_token`**: são usados no passo 4. - **O token da Meta não volta** em nenhuma resposta nem evento. - **`waba_id`** é necessário para listar e enviar modelos. - **`app_secret`** faz a Orkesio conferir a assinatura de cada aviso da Meta (`X-Hub-Signature-256`) e recusar o que não veio dela. Recomendado. - Para trocar o token ou os dados depois, chame a rota de novo. ### 4. Receber as mensagens Para a Meta mandar as mensagens recebidas, três coisas precisam estar ligadas: 1. **O webhook do app.** Em **WhatsApp → Configuração**, preencha **URL de callback** com `webhook_url` e **Verificar token** com `verify_token`, e assine o campo **`messages`**. Mesmo com `webhook_configured: true`, a Meta só manda o que o app assina. 2. **O app inscrito na conta do WhatsApp.** Uma vez por conta: ```bash curl -X POST "https://graph.facebook.com/v24.0//subscribed_apps" \ -H "Authorization: Bearer " ``` A resposta é `{"success": true}`. 3. **O app publicado.** No topo do painel do app, troque o modo de **Desenvolvimento** para **Ativo** (Live). Em desenvolvimento, a Meta não envia parte dos avisos. Mande uma mensagem do seu celular para o número: ela chega como [`message.received`](/webhook/message.received) no [`GET /events`](/docs/eventos) e no [webhook](/docs/eventos#webhook). ## API oficial pela Kapso Você cria uma conta sua na [Kapso](https://kapso.ai). Ela faz o cadastro na Meta e repassa a API dela sem mudar o formato. Confira no site deles os preços e como pagar as mensagens da Meta (pelos créditos da Kapso ou pelo seu cartão na Meta). Na Kapso dá para ligar o número de dois jeitos: - **Só na API** (**Bring your own SIM**): o número sai do app do celular, como no caminho do app próprio. - **No app e na API ao mesmo tempo** (**WhatsApp Business App**, a coexistência): você continua usando o app WhatsApp Business no celular. O que você manda pelo app chega na Orkesio como mensagem enviada (`direction: "out"`), e o que chega no número aparece nos dois. Veja [o que muda](#o-que-muda-na-coexistencia). **Antes de começar:** uma [inbox nova](#criar-a-inbox) na Orkesio. Para a coexistência, o número precisa estar ativo no app **WhatsApp Business** (não no WhatsApp comum), com o app atualizado e o celular por perto. ### 1. Ligar o número na Kapso 1. Crie a conta em [app.kapso.ai](https://app.kapso.ai) e um projeto. 2. Em **Connected numbers → Connect new number**, escolha **WhatsApp Business App** (coexistência) ou **Bring your own SIM** (só na API). Abre o cadastro da Meta. 3. Entre com o Facebook que tem acesso à empresa, digite o número e escolha o portfólio empresarial. 4. **Coexistência:** a Meta mostra um QR code. No celular, no app WhatsApp Business, toque no ícone da câmera em **Conversas**, leia o QR code e confirme **Conectar à plataforma**. Escolha se compartilha o histórico das conversas (não dá para mudar depois). Para o histórico entrar na Orkesio, faça os passos 3 e 4 logo em seguida: veja [o que muda](#o-que-muda-na-coexistencia). **Só na API:** confirme o número pelo código que a Meta manda por SMS ou ligação. 5. Termine o cadastro no navegador, confirmando a conta e o fuso horário. Os passos com as telas estão no [guia da Kapso](https://docs.kapso.ai/docs/how-to/whatsapp/connect-whatsapp). ### 2. Pegar os dados na Kapso - No número conectado: o **ID do número** (`phone_number_id`) e o **ID da conta do WhatsApp Business** (`waba_id`). - Nas configurações do projeto: crie uma **chave de API** (API key). ### 3. Ligar a inbox [`POST /inbox/cloud`](/endpoint/post/inbox~cloud), com o endereço da Kapso e o header da chave: ```json { "phone_number_id": "106737339089002", "token": "", "waba_id": "102692966164644", "base_url": "https://api.kapso.ai/meta/whatsapp/v24.0", "auth_header": "X-API-Key" } ``` Não mande `app_secret`: a Kapso assina os avisos de outro jeito, e a Orkesio recusaria todos. A autenticação fica no segredo da `webhook_url`, que só a Kapso conhece. ### 4. Receber as mensagens pela Kapso Na Kapso, abra o número conectado, clique em **Edit** e preencha o **Webhook destination URL** com o `webhook_url` da resposta. A Kapso repassa os avisos da Meta do jeito que vêm, e a Orkesio entende esse formato. Mande uma mensagem de outro celular para o número: ela chega na Orkesio como [`message.received`](/webhook/message.received). Na coexistência, ela aparece também no app, e a resposta pelo app chega como mensagem enviada. ### O que muda na coexistência - **Aparelhos conectados saem.** O WhatsApp Web e o computador ligados ao número são desconectados no cadastro. Por isso o mesmo número não pode ter também uma inbox pelo WhatsApp Web na Orkesio. - **Grupos não passam pela API**, só as conversas individuais. - **Vazão menor:** até 20 mensagens por segundo pela API ([limites da Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users#limitations)). - **Conversas antigas entram se o histórico for compartilhado**: até 180 dias das conversas individuais, como mensagens antigas da conversa. Elas não contam como não lidas e não saem como [`message.received`](/webhook/message.received). A Meta manda o histórico uma vez só, nas primeiras 24 horas: ele só chega se o **Webhook destination URL** já estiver preenchido ([passo 4](#4-receber-as-mensagens-pela-kapso)). Mídia com mais de 14 dias fica marcada como indisponível, porque a Meta não manda o arquivo. - **O que sai pelo app é grátis**; o que sai pela API a Meta cobra, como num número só da API. ## Enviar pela API oficial Pelos dois caminhos, [`POST /messages`](/endpoint/post/messages) funciona igual ao WhatsApp Web, com duas diferenças: - **Janela de 24 horas.** Mensagem livre (texto, mídia, botões) só vai para quem falou com o número nas últimas 24 horas. Para iniciar uma conversa, ou depois disso, use um modelo aprovado: `"type": "template"` ([exemplo](/docs/envio-modelo)). Os modelos da conta estão em [`GET /inbox/cloud/templates`](/endpoint/get/inbox~cloud~templates); crie com [`POST /inbox/cloud/templates`](/endpoint/post/inbox~cloud~templates) (a Meta revisa antes de liberar) e apague com [`DELETE /inbox/cloud/templates`](/endpoint/delete/inbox~cloud~templates). Editar não existe: apague e crie de novo. - **Envio na hora.** A resposta volta depois que a Meta aceita, com o id da Meta, ou com o erro (janela fechada, modelo reprovado). Veja [Enviar mensagens](/docs/enviar). - **Qualidade e limite do número.** O [`GET /inbox/status`](/endpoint/get/inbox~status) traz `quality_rating` (`green`, `yellow`, `red`) e `messaging_limit_tier` (quantas pessoas a conta pode contatar primeiro em 24 horas), lidos da Meta a cada 10 minutos. Com a qualidade em `red` por uma semana, a Meta baixa o limite. Tipos que a Meta não tem (enquete, carrossel, cobrança, evento) respondem `501 unsupported_for_channel`. **A API oficial é só da Orkesio.** A inbox oficial (e a do Instagram e do Messenger) atende as rotas da Orkesio que [O que funciona em cada canal](/docs/canais) marca para ela: mensagens, eventos, webhooks, conversas, reação, lida, "digitando", mídia, chatbot, fluxos, respostas rápidas, leads e o Chatwoot. As rotas da uazapi (`/send/*`, `/message/*`, `/webhook`, `/instance/status`...) respondem `501` com `error: unsupported_for_channel`. ## Instagram e Messenger Uma inbox do Instagram é uma conta profissional (Business ou Creator), ligada a uma Página do Facebook; uma do Messenger é a própria Página. As duas usam um app na Meta: - **O seu próprio app**, sem a marca da Orkesio em lugar nenhum. Para atender só as suas contas, ele não precisa de App Review nem de verificação da empresa. - **O app da Orkesio**, quando ele for publicado: vira um botão "Conectar com o Facebook" no painel, sem criar app. ### Antes de começar 1. **App na Meta.** Em [developers.facebook.com](https://developers.facebook.com/apps), crie um app do tipo Business e adicione o caso de uso de mensagens do Messenger (e, para o Instagram, o do Instagram pela Página). 2. **Permissões.** No caso de uso, deixe "Pronto para teste" (em "Adicionar à análise do app", sem enviar à análise): `pages_show_list`, `pages_messaging`, `pages_manage_metadata` e `business_management`; no Instagram, também `instagram_basic` e `instagram_manage_messages`. 3. **Instagram ligado à Página.** No app do Instagram (Configurações > Conta > Compartilhar com a Página) ou nas configurações da Página. Ligue também "Permitir acesso às mensagens", nas configurações de mensagens do Instagram (Ferramentas conectadas): sem isso, a Meta não entrega as DMs ao app. 4. **Quem testa.** Enquanto o app estiver em desenvolvimento, só quem tem papel no app (administrador, desenvolvedor, testador) faz o login e conversa com a conta. Para atender qualquer pessoa, publique o app: a Meta pede a URL da política de privacidade em Configurações do app > Básico. ### A. Pelo login (recomendado) 1. Numa inbox nova, [`POST /inbox/cloud/login`](/endpoint/post/inbox~cloud~login): ```json POST /inbox/cloud/login { "channel": "instagram", "app_id": "941970291976551", "app_secret": "..." } ``` Para o Messenger, `"channel": "messenger"`. A resposta traz o link do login e o `redirect_uri`. 2. No app, cadastre o `redirect_uri` em "URIs de redirecionamento do OAuth válidos" (Login do Facebook para Empresas > Configurações) e o domínio dele em "Domínios do app" (Configurações do app > Básico). 3. O dono da Página abre o link (vale 15 minutos), autoriza e escolhe a Página. A Orkesio guarda o token, assina a Página nos eventos e cadastra o webhook do app sozinha. 4. A página final diz se ligou. "Falta o webhook" ou "falta assinar a Página": veja a tabela abaixo. Confira a qualquer hora com [`GET /inbox/status`](/endpoint/get/inbox~status). ### B. Com o token da Página 1. **Token e `page_id`.** Nas configurações do Messenger do app, adicione a Página e gere o token dela. O `page_id` é o número que aparece ao lado do nome da Página nessa lista. Guarde também o App Secret (Configurações do app > Básico). 2. **Ligar a inbox.** Numa inbox nova: ```json POST /inbox/cloud { "channel": "instagram", "page_id": "110198307512345", "token": "EAAG...", "app_secret": "..." } ``` Para o Messenger, `"channel": "messenger"`. A resposta traz `webhook_url`, `verify_token` e `webhook_configured` (a Página foi assinada nos eventos). 3. **Webhook.** Em Webhooks, no painel do app, cole `webhook_url` como URL de callback e `verify_token` como token de verificação, nos objetos Page (Messenger) e Instagram. Os nomes dos campos mudam de um objeto para o outro: | Página (Messenger) | Instagram | |---|---| | `messages`, `messaging_postbacks`, `message_reactions`, `message_echoes` | `messages`, `messaging_postbacks`, `message_reactions` | | `message_reads`, `message_deliveries` | `messaging_seen` | | `message_edits` | `message_edit` | | `messaging_referrals`, `standby` | `messaging_referral`, `standby` | | `feed` (comentários) | `comments` (comentários) | ### Como funciona - **O contato começa a conversa.** A conversa é `@instagram` ou `@messenger`: sem telefone, grupos nem histórico antigo. Só conversa 1:1. - **Janela de 24 horas.** A resposta livre vale por 24 horas depois da última mensagem do contato (`reply_window_until` na conversa). Fora dela, o `POST /messages` responde `outside_window`. Com `options.human_agent: true`, um atendente humano responde até 7 dias depois, se o app tiver a permissão Human Agent (aprovada na análise da Meta). - **Envio.** - Nos dois, a legenda sai numa mensagem à parte, logo depois da mídia. Se só a legenda falhar, a resposta vem 200 com `warning` (`partial_send`): não reenvie a mídia. - No Instagram, a mídia em `base64` fica guardada na inbox e a Meta baixa de lá (só imagem, vídeo, áudio e PDF). - As respostas rápidas somem com a próxima mensagem. - O Instagram reage só com ❤️; o Messenger, com qualquer emoji. - Nenhum dos dois edita nem apaga a mensagem enviada. - **Caixa de entrada da Meta.** Quando um atendente responde pela caixa da Meta, a conversa fica com ela: as mensagens do contato chegam, mas o chatbot não responde, e o envio pela API pode responder `conversation_taken`. - **Depois de uma queda do seu lado**, o [`POST /chats/history-sync`](/endpoint/post/chats~history-sync) traz as 20 mensagens mais novas da conversa e grava as recebidas que faltarem. Reação, edição e clique em botão não voltam. - O que cada rota faz em cada canal está em [O que funciona em cada canal](/docs/canais). **Comentários:** cada post comentado vira uma conversa do tipo `post` (`@instagram_post` ou `@facebook_post`) e cada comentário, uma mensagem dela: chega em `message.received`, aparece na busca e na lista de conversas (`GET /chats?type=post`). Para responder em público, [`POST /messages`](/endpoint/post/messages) com `to` no post e `reply_to` no comentário. Para responder no privado (o "comente e receba no direct": um por comentário, até 7 dias depois), o mesmo `POST /messages` com `to` na pessoa (o `author.id` do comentário) e `reply_to` no comentário. Chatbot e IA não respondem em post. O app precisa das permissões `instagram_manage_comments` (Instagram) ou `pages_read_engagement`, `pages_read_user_content` e `pages_manage_engagement` (Página), que o login já pede. Inbox ligada antes disso: conecte de novo para receber os comentários. **Perguntas prontas:** [`PUT /inbox/ice-breakers`](/endpoint/put/inbox~ice-breakers) mostra até 4 perguntas para o contato que abre a conversa pela primeira vez. O clique chega como `interactive_reply` com o `payload` de cada uma. ## Telegram Uma inbox do Telegram é um bot seu. Com o Telegram Business, a mesma inbox atende também as conversas da sua conta pessoal no Telegram, pelo bot. Não há app para criar nem webhook para colar. ### 1. Criar o bot No Telegram, fale com o [@BotFather](https://t.me/BotFather), mande `/newbot` e escolha o nome e o @ do bot. Ele devolve o token do bot (algo como `123456789:AAH...`). Guarde-o: quem tem o token controla o bot. ### 2. Ligar a inbox Numa inbox nova, [`POST /inbox/cloud`](/endpoint/post/inbox~cloud): ```json POST /inbox/cloud { "channel": "telegram", "token": "123456789:AAH...", "business_username": "minhaloja" } ``` A Orkesio confere o token e aponta o webhook do bot para a inbox sozinha: a resposta vem com `webhook_configured: true`. `business_username` é o @ da sua conta no Telegram (sem o `@`) e só é preciso para o Telegram Business. Sem ele, a inbox atende só as conversas com o bot. Sempre que chamar esta rota de novo (para trocar o token, por exemplo), mande o mesmo `business_username`: sem ele, o Telegram Business desliga. ### 3. Telegram Business (opcional) O Telegram Business liga o bot à sua conta: quem fala com você no Telegram passa a cair na inbox, e a inbox responde por você. Não precisa de Telegram Premium. 1. No @BotFather, abra o bot (`/mybots` → o bot → Bot Settings) e ligue o **Business Mode** (em algumas versões, **Secretary Mode**). 2. No **app do celular**, em Configurações → Telegram Business → **Chatbots** (em algumas versões, **Chat Automation**), escolha o bot pelo @, marque as conversas que ele atende, dê a permissão de **responder** (e a de **apagar**, para apagar mensagens pela API) e **salve**. Sem salvar, o Telegram não manda nada. O Telegram Web e o de computador não mostram essa tela. A inbox aceita a ligação só da conta de `business_username`: o bot é público, e a ligação de qualquer outra conta é ignorada. Depois da primeira ligação, a inbox fica presa a essa conta, mesmo que o @ mude de dono. Para trocar de conta, chame o `POST /inbox/cloud` de novo com o novo `business_username`. O que chegou antes da ligação não volta: o Telegram não entrega histórico ao bot. ### Como funciona - **Duas conversas.** Com a mesma pessoa, a conversa com o bot (`@telegram`) e a da sua conta (`@telegram-business`) são diferentes. O id da mensagem é `_`, com um `b` na frente no Telegram Business (`b_`). Só conversa 1:1: grupos e canais do Telegram ficam de fora. - **O contato começa.** O bot não puxa conversa: o contato fala primeiro (o `/start`). Para quem nunca falou com o bot ou o bloqueou, o envio responde `recipient_unavailable`. - **Sem janela de 24 horas** na conversa com o bot: responda quando quiser. - **No Telegram Business, a resposta sai da sua conta**, com o rótulo do bot embaixo, e as mensagens que você manda pelo celular também chegam na inbox (como enviadas). - **Envio:** texto, mídia (com a legenda junto em imagem, vídeo e documento), botões (respostas e links), localização e contato. Sem modelo nem lista: a lista vira um botão por item. A formatação do WhatsApp (`*negrito*`, `_itálico_`, `~riscado~`, `` `código` ``) sai formatada no Telegram. Detalhes em [Enviar mensagens](/docs/enviar). - **Clique em botão:** o clique não aparece na conversa do contato (vai só ao bot). Ele vê um aviso rápido com o texto do botão, e a inbox recebe a resposta como `interactive_reply`. - **Editar e apagar:** [`PATCH /messages`](/endpoint/patch/messages) edita o texto (ou a legenda) das mensagens enviadas pela inbox (no Telegram Business, até 48 horas depois), e [`DELETE /messages/{message_id}`](/endpoint/delete/messages~:message_id) apaga até 48 horas depois do envio. Na conversa com o bot, dá para apagar também a mensagem do contato. - **Reação:** a inbox reage na conversa com o bot, com os emojis que o Telegram aceita para bots. No Telegram Business, a reação não sai pela API. A reação do contato não chega: o Telegram não a entrega ao bot em conversa privada. - **Lido e "digitando":** "digitando" funciona nas duas conversas. "Lido" só existe no Telegram Business; na conversa com o bot, o Telegram não mostra leitura. - **Mídia recebida:** baixe pelo [`POST /messages/media`](/endpoint/post/messages~media), até 20 MB por arquivo. - **Enquete, dado, cobrança, jogo e story** do contato chegam como `unavailable` (`reason: "unsupported"`): a conversa mostra que veio algo, mas o conteúdo fica no Telegram. - O que cada rota faz em cada canal está em [O que funciona em cada canal](/docs/canais). ## Se a API oficial não ligar | O que aconteceu | O que fazer | |---|---| | `400` com erro da Meta ao ligar | Token sem acesso ao número, `phone_number_id` errado ou token expirado. Gere o token de novo (passo 2), com o app e a conta atribuídos. | | `409` ao ligar | A inbox já foi conectada pelo QR code. Crie uma inbox nova. | | `webhook_configured: false` | O token não tem `whatsapp_business_management`. Configure o webhook à mão (passo 4.1). Na Kapso, configure no painel dela (passo 4 da Kapso). | | Envio responde que o número não está registrado | Registre o número com o PIN de duas etapas: `POST https://graph.facebook.com/v24.0//register` com `{"messaging_product": "whatsapp", "pin": "123456"}`. | | As mensagens recebidas não chegam | App próprio: confira os três itens do passo 4. Kapso: confira o webhook do número e não mande `app_secret`. O painel da Meta tem um botão **Testar** para cada campo do webhook. | | Envio fora das 24 horas recusado (`outside_window`) | WhatsApp: use um modelo aprovado (`type: template`). Instagram e Messenger: espere o contato escrever, ou responda como atendente com `options.human_agent: true`. | | `disconnected` (503) ao enviar | O token venceu ou foi revogado (o dono da Página trocou a senha, removeu o app). Conecte a inbox de novo. | | Instagram ou Messenger: "falta assinar a Página" ou `webhook_configured: false` | O login não teve a permissão `pages_manage_metadata`. Conecte de novo, deixando todas as permissões marcadas. | | Instagram ou Messenger: "falta o webhook" | A Meta recusou a URL do webhook no app. Confira se a URL da sua Orkesio é pública e cadastre o webhook à mão (caminho B, passo 3). | | Instagram ou Messenger: as mensagens não chegam | App em desenvolvimento (só quem tem papel no app conversa), campo do webhook não assinado ou, no Instagram, o acesso às mensagens para apps desligado. | | Instagram: a edição feita pelo contato não chega | O campo `message_edit` do objeto Instagram não está assinado. Conecte pelo login de novo, ou assine à mão. | | `human_agent_not_allowed` | O app não tem a permissão Human Agent, que passa pela análise da Meta. | | `recipient_unavailable` | O contato bloqueou a conta ou não pode receber agora. No app em desenvolvimento, ele também precisa ter papel no app. | | Telegram: `400` ao ligar | O Telegram recusou o token. Copie de novo do @BotFather (`/mybots` → o bot → API Token). | | Telegram: `disconnected` (503) ao enviar | O token do bot foi trocado ou revogado no @BotFather. Ligue a inbox de novo com o token novo e o mesmo `business_username`. | | Telegram: `recipient_unavailable` | O contato nunca falou com o bot ou o bloqueou. | | Telegram Business: as conversas da conta não chegam | A ligação não foi salva no celular, foi feita por outra conta ou a inbox foi ligada sem `business_username`. Confira o passo 3 do Telegram. |