Conectar a inbox

Uma inbox é uma conta ligada à Orkesio: um número de WhatsApp, uma conta profissional do Instagram, uma Página do Facebook (Messenger) ou um bot do Telegram. O WhatsApp conecta de um destes dois jeitos, escolhidos uma vez:

O que muda de um para o outro está em O que funciona em cada canal. 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:

{ "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 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. Não repita o connect enquanto conecta.
3. Quando o celular confirmar, status vira connected e chega o evento 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. 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:

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.

Antes de começar

• Um portfólio empresarial na Meta (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), 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, 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:

curl -X POST https://<seu-servidor>/inbox/cloud \
  -H "token: <token-da-inbox>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "1375523705642891",
    "token": "<token-do-usuário-do-sistema>",
    "waba_id": "102692966164644",
    "app_secret": "<chave-secreta-do-app>"
  }'

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:

{
  "inbox": {
    "id": "r183e2ef9597845",
    "name": "loja",
    "status": "connected",
    "channel": "whatsapp_cloud",
    "phone": "5511999999999",
    "profile_name": "Minha Empresa"
  },
  "webhook_url": "https://<seu-servidor>/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:

   curl -X POST "https://graph.facebook.com/v24.0/<waba_id>/subscribed_apps" \
     -H "Authorization: Bearer <token-do-usuário-do-sistema>"
   

   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 no GET /events e no webhook.

API oficial pela Kapso

Você cria uma conta sua na Kapso. 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.

Antes de começar: uma inbox nova 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 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. 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.

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, com o endereço da Kapso e o header da chave:

{
  "phone_number_id": "106737339089002",
  "token": "<chave-de-API-da-Kapso>",
  "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. 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).
• 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. 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). 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 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). Os modelos da conta estão em GET /inbox/cloud/templates; crie com POST /inbox/cloud/templates (a Meta revisa antes de liberar) e apague com 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.
• Qualidade e limite do número. O 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 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, 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:

   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.

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:

   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 é <id>@instagram ou <id>@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 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.

Comentários: cada post comentado vira uma conversa do tipo post (<id>@instagram_post ou <id>@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 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 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, 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:

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 (<id>@telegram) e a da sua conta (<id>@telegram-business) são diferentes. O id da mensagem é <conversa>_<número>, com um b na frente no Telegram Business (b<conversa>_<número>). 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.
• 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 edita o texto (ou a legenda) das mensagens enviadas pela inbox (no Telegram Business, até 48 horas depois), e 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, 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.

Se a API oficial não ligar