Como permitir que os seus utilizadores ligam contas de WhatsApp, Instagram e TikTok à sua aplicação
Para permitir que os seus utilizadores liguem contas de WhatsApp, Instagram e TikTok à sua aplicação, crie uma sessão de ligação com a Partner API da easyCoexistence e envie o utilizador para o url alojado. Aí, ligam um número de WhatsApp através do Embedded Signup da Meta ou iniciam sessão no Instagram, Facebook, TikTok, YouTube, LinkedIn e mais canais, e depois regressam ao seu redirect_url com o id da nova ligação ou do novo canal. Os links duram uma hora.
Por quanto tempo um link de ligação funciona; depois disso, a sessão aparece como expirada e é preciso criar um novo.
Sessões de ligação que uma conta pode manter abertas em simultâneo, a par de um limite de 100 novas sessões por hora.
Uma sessão é criada, aberta, ligada, cancelada ou expirada, conforme indica GET /connect-sessions/:id.
O URL de callback alternativo mais longo que a Meta aceita para encaminhar para outro destino os webhooks de mensagens de um número de WhatsApp.
Como funciona um link de ligação?
Como uma página de pagamento. O seu backend cria uma sessão, a sua interface envia o cliente para o url da sessão, o cliente liga-se numa página em easycoexistence.com, e o navegador regressa ao seu redirect_url. Depois, o seu backend confirma o resultado e obtém as credenciais da nova ligação, tudo com a sua chave de API.
O que vai no pedido?
Um corpo JSON enviado por POST para https://easycoexistence.com/api/v1/connect-sessions, com a sua chave de API como Bearer token. Só redirect_url é obrigatório:
redirect_url: um URL https para onde o cliente vai depois.- channel: whatsapp, por predefinição, ou uma rede social disponível na sua conta, pelo nome em minúsculas, como instagram, tiktok ou youtube.
external_ref: o seu próprio identificador deste cliente, até 200 caracteres.partner_name: o nome que a página alojada mostra, até 80 caracteres; por predefinição, o nome da sua conta.webhook_urlcomwebhook_verify_token: apenas para números, e sempre em conjunto. A Meta entrega aí as mensagens do número desde o momento da ligação.
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 o url e guarde o id, que começa por cs_, para consultar a sessão mais tarde. O expires_at é definido uma hora depois da criação, e o connection_id ou o channel_id é preenchido assim que o cliente se liga, consoante o canal da sessão. GET /connect-sessions/:id devolve a mesma estrutura 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"
}Que erros pode devolver a criação de uma sessão?
Cada erro tem o mesmo corpo, um objeto com um code e uma message, e a message diz o que corrigir. A criação de uma sessão pode devolver:
- 400
invalid_jsonouinvalid_request: o corpo não é um objeto JSON, ou um campo falhou a validação, como umredirect_urlque não é https. - 400
channel_unavailable: o canal não está disponível para esta conta; a message indica quais estão disponíveis. - 401 unauthorized: a chave de API está em falta ou é inválida.
- 402
billing_required: a conta ainda não tem cartão, e tudo o que se liga através dela é faturado nessa conta. - 429
cap_reached: já estão abertas 50 sessões; aguarde que algumas terminem ou expirem. - 429
rate_limited: mais de 100 sessões nesta hora; a message indica quanto tempo esperar.
Para onde vai o cliente depois?
Para o seu redirect_url, com o resultado acrescentado à query string. O mesmo resultado está 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 identificador do cliente, quando a sessão o incluiu.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=…Que estados pode ter uma sessão?
Cinco. GET /connect-sessions/:id indica o estado atual, com opened_at, finished_at e last_error, que indica o motivo da última falha:
- created: criada pelo seu backend, ainda não aberta.
- opened: o cliente carregou a página alojada.
- connected: um número ou uma conta social foi ligado, e o seu id está na sessão.
- cancelled: o cliente saiu através de Cancelar e voltar.
- expired: a hora esgotou-se antes de a sessão terminar.
Quanto tempo funciona um link?
Uma hora a partir da criação. Depois disso, a página alojada informa o cliente de que o link expirou, com um botão para voltar ao seu redirect_url marcado com status=cancelled, e a sessão aparece como expirada. Uma conta pode ter 50 sessões abertas e criar 100 por hora, porque a Meta conta cada integração inicial contra um limite de toda a aplicação que todas as contas partilham.
Para que serve external_ref?
Liga cada ligação ao seu cliente. O valor que envia fica guardado no número ou canal que a sessão cria, acrescentado ao redirecionamento e incluído em cada evento de estado sobre ele, pelo que GET /connections?external_ref=customer_4821 e GET /channels?external_ref=customer_4821 listam o que esse cliente ligou. Um início de sessão no Facebook ou no LinkedIn pode trazer várias Páginas de uma vez: o redirecionamento indica a primeira, e o filtro lista as restantes. Utilize um identificador estável da sua própria base de dados, e não um email, que pode mudar.
E se o cliente cancelar ou o início de sessão falhar?
Depende de onde aconteceu, e a sessão guarda o registo:
- A janela pop-up da Meta falha ou é fechada: o cliente volta a carregar em Ligar na mesma página, enquanto o link estiver aberto.
- Um início de sessão numa rede social é cancelado ou recusado: o cliente regressa à página alojada com o motivo e pode voltar a tentar até o link expirar.
- A conta já está ligada através de outra conta da easyCoexistence: o
last_errordiz isso, e o cliente inicia sessão com outra. - O cliente escolhe Cancelar e voltar: o seu
redirect_urlrecebe status=cancelled e a sessão fecha-se, por isso crie uma nova para tentar de novo. - O link expirou: crie uma nova sessão.
E se um número ligar sem o token do cliente?
Por vezes, a Meta conclui o Embedded Signup sem emitir o token de negócio próprio do cliente. A página alojada pede então mais uma passagem, que demora alguns segundos. Se o cliente a dispensar, a sessão aparece como connected com token_ready false, e o seu URL de eventos recebe connection.token_missing: o número recebe mensagens, uma vez que os seus ids são válidos, mas não consegue enviar até que uma nova sessão de ligação o volte a ligar e emita o token.
E se o webhook_url não passar a verificação da Meta?
O número liga-se de qualquer forma. 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 por «webhook_url was not applied» e indica o motivo dado pela Meta, e PUT /connections/:id/webhook define o destino assim que o endpoint responder. Se for definido nas 24 horas após a ligação, continua a receber a importação única de contactos e, se o cliente tiver concordado em partilhá-lo, o histórico de conversas.
O que vê o cliente?
Uma página em easycoexistence.com com o seu nome, vindo de partner_name, e sem conta, email nem cartão para preencher. Para um número de WhatsApp, mostra uma lista curta de verificação de elegibilidade, depois o pop-up da Meta e um código QR para ler com a app do WhatsApp Business. Para uma conta social, mostra um só botão, como Continuar com o TikTok, que abre o ecrã de consentimento da própria rede no mesmo separador, pelo que funciona também nos telemóveis.
Erros comuns
- Confiar só na query string. Qualquer pessoa pode escrever status=connected num URL, por isso confirme com GET /connect-sessions/:id a partir do seu backend antes de marcar o cliente como ligado.
- Incorporar o link num iframe. Envie o cliente para ele com um redirecionamento ou um novo separador, que é a forma como a página alojada e os inícios de sessão que abre foram pensados para funcionar.
- Criar links com antecedência. Cada um funciona durante uma hora e todos os abertos contam para o limite de 50, por isso crie a sessão quando o cliente estiver prestes a ligar-se.
- Enviar um webhook_url com mais de 200 caracteres. A Meta aceita URLs alternativas de callback até 200 caracteres, por isso um URL mais longo não é aplicado e o número liga-se sem ele.
A easyCoexistence liga os números de WhatsApp dos seus clientes e as contas de Instagram, Facebook, TikTok, YouTube e LinkedIn deles, bem como mais canais, ao seu software através de um único link alojado. Depois, entrega ao seu backend as credenciais de cada ligação, os webhooks e os eventos de estado assinados. De US$ 9 a US$ 0.75 por ligação por mês, com preço que desce à medida que adiciona ligações e os primeiros 3 dias grátis.
Perguntas frequentes
Um link de ligação pode ser utilizado duas vezes?
Não. Um link termina com um número ou com um início de sessão numa rede social, que no Facebook ou no LinkedIn pode trazer várias Páginas. Depois disso fica como ligado, por isso crie uma nova sessão para a ligação seguinte.
Posso enviar o link por email ou chat?
Sim, desde que o cliente o abra dentro da hora. O id da sessão no URL é o que autoriza a página, por isso envie cada link apenas ao cliente para quem foi criado.
A página alojada funciona nos telemóveis?
Os inícios de sessão em redes sociais funcionam, já que abrem no mesmo separador. Um número de WhatsApp é melhor ligá-lo a partir de um computador: num telemóvel, o pop-up da Meta abre como um novo separador, e é preciso o próprio telemóvel para ler o código QR.
Como sei que um cliente se ligou sem fazer polling?
Defina um URL de eventos de estado no painel, em Perfil, Developers. A easyCoexistence envia então connection.connected ou channel.connected, assinados e com o seu external_ref, assim que a ligação estiver feita.
Continue a ler
Ligue o seu primeiro canal em dois minutos.
Sem revisões de plataformas para esperar. Ligue o WhatsApp, o Instagram, o TikTok ou outro canal, peça depois à sua IA que publique, responda ou faça um relatório, e veja-a trabalhar.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorizado 24/7
Verificado em