Como permitir que seus usuários conectem contas de WhatsApp, Instagram e TikTok ao seu app
Para permitir que seus usuários conectem contas de WhatsApp, Instagram e TikTok ao seu app, crie uma sessão de conexão com a Partner API do easyCoexistence e envie o usuário para a url hospedada dela. Lá ele conecta um número de WhatsApp pelo Embedded Signup da Meta ou entra no Instagram, Facebook, TikTok, YouTube, LinkedIn e mais canais, depois volta para o seu redirect_url com o id da nova conexão ou do canal. Os links valem por uma hora.
Por quanto tempo um link de conexão funciona; depois disso a sessão aparece como expirada e é preciso criar uma nova.
Sessões de conexão que uma conta pode manter abertas ao mesmo tempo, somadas ao limite de 100 novas sessões por hora.
Uma sessão é criada, aberta, conectada, cancelada ou expirada, conforme informa GET /connect-sessions/:id.
A maior URL de callback alternativa que a Meta aceita para direcionar os webhooks de mensagens de um número de WhatsApp a outro destino.
Como funciona um link de conexão?
Como uma página de checkout. Seu backend cria uma sessão, sua interface envia o cliente para a url dela, o cliente conecta em uma página em easycoexistence.com, e o navegador volta para o seu redirect_url. Depois, seu backend confirma o resultado e busca as credenciais da nova conexão, tudo com a sua chave de API.
O que vai na requisição?
Um corpo JSON enviado por POST para https://easycoexistence.com/api/v1/connect-sessions, com sua chave de API como token Bearer. Apenas redirect_url é obrigatório:
redirect_url: uma URL https para onde o cliente vai depois.- channel: whatsapp, o padrão, ou uma rede social aberta à sua conta, pelo nome em minúsculas, como instagram, tiktok ou youtube.
external_ref: seu próprio id para este cliente, até 200 caracteres.partner_name: o nome que a página hospedada mostra, até 80 caracteres; por padrão, o nome da sua conta.webhook_urlcomwebhook_verify_token: apenas para números, e sempre juntos. A Meta entrega ali as mensagens do número desde o momento em que ele se conecta.
curl -X POST https://easycoexistence.com/api/v1/connect-sessions \
-H "Authorization: Bearer $EC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"channel": "whatsapp",
"redirect_url": "https://app.example.com/connect/return",
"external_ref": "customer_4821",
"partner_name": "ClinicApp",
"webhook_url": "https://hooks.example.com/wa/<long-random-secret>",
"webhook_verify_token": "another-long-random-string"
}'O que volta?
Um 201 com a sessão. Envie o cliente para a url e guarde o id, que começa com cs_, para consultar a sessão depois. expires_at vence uma hora após a criação, e connection_id ou channel_id é preenchido quando o cliente conecta, conforme o canal da sessão. GET /connect-sessions/:id retorna o mesmo formato a qualquer momento.
{
"id": "cs_…",
"url": "https://easycoexistence.com/connect/cs_…",
"channel": "whatsapp",
"status": "created",
"external_ref": "customer_4821",
"connection_id": null,
"channel_id": null,
"token_ready": false,
"redirect_url": "https://app.example.com/connect/return",
"webhook_url": "https://hooks.example.com/wa/<long-random-secret>",
"last_error": null,
"expires_at": "2026-10-31T15:00:00.000Z",
"opened_at": null,
"finished_at": null,
"created_at": "2026-10-31T14:00:00.000Z"
}Quais erros a criação de uma sessão pode retornar?
Cada erro tem o mesmo corpo, um objeto com um code e uma message, e a message diz o que corrigir. Criar uma sessão pode retornar:
- 400
invalid_jsonouinvalid_request: o corpo não é um objeto JSON, ou um campo falhou na validação, como umredirect_urlque não é https. - 400
channel_unavailable: o canal não está aberto a esta conta; a message lista os que estão. - 401 unauthorized: a chave de API está ausente ou é inválida.
- 402
billing_required: a conta ainda não tem cartão, e tudo o que for conectado por meio dela é cobrado nele. - 429
cap_reached: já há 50 sessões abertas; aguarde algumas terminarem ou expirarem. - 429
rate_limited: mais de 100 sessões nesta hora; a message informa quanto tempo esperar.
Para onde o cliente vai depois?
Para o seu redirect_url, com o resultado acrescentado à query string. O mesmo resultado fica na sessão, que o seu backend lê com GET /connect-sessions/:id:
- session: o id da sessão, cs_ seguido de caracteres aleatórios.
- status: connected, ou cancelled quando o cliente escolheu Cancelar e voltar.
external_ref: o seu id para o cliente, quando a sessão trouxe um.connection_id: o id do novo número, para /connections.channel_id: o id da nova conta social, para /channels.
https://app.example.com/connect/return?session=cs_…&status=connected&external_ref=customer_4821&connection_id=…Quais status uma sessão pode ter?
Cinco. GET /connect-sessions/:id informa o atual, com opened_at, finished_at e last_error, que diz por que a última tentativa falhou:
- created: criada pelo seu backend, ainda não aberta.
- opened: o cliente carregou a página hospedada.
- connected: um número ou uma conta social foi conectado, e o id dele está na sessão.
- cancelled: o cliente saiu pelo botão Cancelar e voltar.
- expired: a hora acabou antes de a sessão terminar.
Por quanto tempo um link funciona?
Uma hora a partir da criação. Depois disso, a página hospedada informa ao cliente que o link expirou, com um botão de volta para o seu redirect_url marcado com status=cancelled, e a sessão aparece como expirada. Uma conta pode manter 50 sessões abertas e criar 100 por hora, porque a Meta conta cada onboarding de primeira vez contra um limite do app que todas as contas compartilham.
Para que serve external_ref?
Ele vincula cada conexão ao seu cliente. O valor enviado é guardado no número ou canal que a sessão cria, acrescentado ao redirecionamento e incluído em todo evento de status sobre ele; assim, GET /connections?external_ref=customer_4821 e GET /channels?external_ref=customer_4821 listam o que esse cliente conectou. Um login do Facebook ou do LinkedIn pode trazer várias Páginas de uma vez: o redirecionamento informa a primeira, e o filtro lista as demais. Use um id estável do seu próprio banco de dados, não um e-mail que pode mudar.
E se o cliente cancelar ou o login falhar?
Depende de onde aconteceu, e a sessão mantém o registro:
- O pop-up da Meta falha ou é fechado: o cliente aperta Conectar de novo na mesma página, enquanto o link estiver aberto.
- Um login social é cancelado ou recusado: o cliente volta para a página hospedada com o motivo e pode tentar de novo até o link expirar.
- A conta já está conectada por meio de outra conta easyCoexistence:
last_errorinforma isso, e o cliente entra com outra conta. - O cliente escolhe Cancelar e voltar: o seu
redirect_urlrecebe status=cancelled e a sessão se encerra, então crie uma nova para outra tentativa. - O link expirou: crie uma nova sessão.
E se um número conectar sem o token do cliente?
Às vezes a Meta conclui o Embedded Signup sem emitir o token empresarial próprio do cliente. A página hospedada então pede mais uma etapa, que leva alguns segundos. Se o cliente pular, a sessão aparece como connected com token_ready false, e a sua URL de eventos recebe connection.token_missing: o número recebe mensagens, pois os seus ids são válidos, mas não consegue enviar até que uma nova sessão de conexão o reconecte e emita o token.
E se o webhook_url não passar na verificação da Meta?
O número conecta mesmo assim. A Meta verifica um webhook_url com um handshake GET, que o seu endpoint passa ao devolver hub.challenge quando hub.verify_token coincide. Se falhar, o last_error da sessão começa com webhook_url was not applied e traz o motivo da Meta, e PUT /connections/:id/webhook define o destino assim que o endpoint responder. Definido em até 24 horas após a conexão, ele ainda recebe a importação única de contatos e, se o cliente tiver concordado em compartilhar, o histórico de conversas.
O que o cliente vê?
Uma página em easycoexistence.com com o seu nome vindo de partner_name, e nenhuma conta, e-mail ou cartão para preencher. Para um número de WhatsApp, ela mostra uma lista curta de elegibilidade, depois o pop-up da Meta e um QR code para escanear com o app do WhatsApp Business. Para uma conta social, mostra um único botão, como Continuar com TikTok, que abre a tela de consentimento da própria rede na mesma aba, então funciona também em celulares.
Erros comuns
- Confiar apenas na query string. Qualquer pessoa pode digitar status=connected em uma URL, então confirme com GET /connect-sessions/:id no seu backend antes de marcar o cliente como conectado.
- Incorporar o link em um iframe. Envie o cliente até ele com um redirecionamento ou em uma nova aba, que é como a página hospedada e os logins que ela abre devem funcionar.
- Criar links antecipadamente. Cada um vale por uma hora e todo link aberto conta para o limite de 50, então crie a sessão quando o cliente estiver prestes a conectar.
- Enviar um webhook_url com mais de 200 caracteres. A Meta aceita URLs de callback alternativas de até 200 caracteres, então uma mais longa não é aplicada e o número conecta sem ela.
O easyCoexistence conecta os números de WhatsApp dos seus clientes e as contas de Instagram, Facebook, TikTok, YouTube e LinkedIn deles, além de outros canais, ao seu software por meio de um único link hospedado, e depois entrega ao seu backend as credenciais, os webhooks e os eventos de status assinados de cada conexão. De US$ 9 a US$ 0.75 por conexão por mês, com o valor caindo conforme você adiciona conexões, e os primeiros 3 dias grátis.
O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.
Perguntas frequentes
Um link de conexão pode ser usado duas vezes?
Não. Um link termina com um número, ou com um login social, que no Facebook ou no LinkedIn pode trazer várias Páginas. Depois disso ele aparece como conectado, então crie uma nova sessão para a próxima conexão.
Posso enviar o link por e-mail ou chat?
Sim, desde que o cliente abra o link dentro da hora. O id da sessão na URL é o que autoriza a página, então envie cada link apenas ao cliente para quem foi criado.
A página hospedada funciona em celulares?
Os logins sociais funcionam, pois abrem na mesma aba. Um número de WhatsApp é melhor conectado pelo computador: no celular, o pop-up da Meta abre como nova aba, e é preciso usar o próprio celular para escanear o QR code.
Como saber que um cliente conectou sem fazer polling?
Defina uma URL de eventos de status no painel, em Perfil, Desenvolvedores. O easyCoexistence então envia connection.connected ou channel.connected, assinado e com o seu external_ref, assim que a conexão é feita.
Continue lendo
Conecte seu primeiro canal em dois minutos.
Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorado 24/7
Verificado em