Como criar um produto de agente de IA no WhatsApp, Instagram e TikTok dos seus clientes
Um produto de agente de IA nos canais dos clientes assenta em três peças: um link de ligação alojado para o número WhatsApp ou a conta social de cada cliente, webhooks que levam as mensagens e os comentários ao seu backend, onde o seu próprio modelo escreve respostas enviadas pela API oficial de cada rede com o token do cliente, e eventos de estado para as ligações que deixam de funcionar. O agente respeita as regras de cada rede, como a janela de 24 horas do WhatsApp.
A easyCoexistence dá aos agentes de IA do seu produto uma voz nos números WhatsApp dos seus clientes e nas contas de Instagram, Facebook, TikTok, YouTube e LinkedIn, e em mais canais: links de ligação alojados, credenciais atualizadas, webhooks e eventos de estado assinados, na API oficial de cada rede, com cada ligação monitorizada 24 horas por dia.
Janela de atendimento ao cliente do WhatsApp após uma mensagem ou chamada do utilizador; cada nova mensagem a reinicia.
O que uma empresa WhatsApp pode enviar depois de fechar a janela de atendimento ao cliente: templates de mensagem pré-aprovados.
As regras da Meta proíbem os fornecedores de IA de usar o WhatsApp para oferecer IA como funcionalidade principal, e não acessória.
Janela para a resposta privada única de uma conta do Instagram a um comentário, contada a partir do momento em que o comentário foi feito.
Throughput fixo de um número usado com a app WhatsApp Business e com a Cloud API.
O que precisa um produto de agente de IA do canal de cada cliente?
Quatro coisas: uma forma de o cliente o ligar, as mensagens chegarem ao seu backend, um token para responder e um aviso quando a ligação deixa de funcionar. A Partner API cobre cada uma delas, enquanto o modelo, os prompts e a lógica da conversa continuam sob o seu controlo. A easyCoexistence liga a conta, mantém o acesso renovado e vigia-a, e as suas respostas seguem do seu backend diretamente para a API da rede.
Como se liga cada cliente?
O seu backend cria uma sessão de ligação com POST /connect-sessions, indicando o canal, um redirect_url e um external_ref para o cliente, e, no caso de um número, o webhook_url e o webhook_verify_token. O cliente abre o link alojado, inicia sessão com Meta, TikTok, Google ou LinkedIn e regressa à sua aplicação com connection_id ou channel_id. Não precisa de conta, email nem cartão na easyCoexistence, e cada ligação feita com a sua chave pertence à sua conta.
Como chegam ao seu modelo as mensagens e os comentários?
Por webhook, nas redes que os enviam. A Meta entrega as mensagens de um número diretamente ao seu webhook_url, e o que a equipa da empresa envia a partir da app WhatsApp Business chega aí como smb_message_echoes. Os comentários, as menções e as mensagens diretas do Instagram e do Facebook, e os comentários do TikTok, são encaminhados para o destino de cada canal, assinados com o respetivo segredo. O YouTube e o LinkedIn não enviam eventos de comentários, por isso o agente lê os novos comentários através das suas APIs, de forma agendada. Responda a cada entrega com 2xx de imediato e deixe um worker chamar o modelo.
Como responde o agente?
Através da API da própria rede, com as credenciais que o seu backend obteve. Uma resposta no WhatsApp é um POST para o send_endpoint do número com o token do cliente; uma mensagem direta no Instagram ou no Facebook vai para o edge messages da conta; uma resposta no TikTok fica por baixo do comentário, através de business/comment/reply/create/. O esboço abaixo responde a mensagens do WhatsApp: verifica o segredo no caminho do URL, coloca em fila cada mensagem recebida e responde com o que o seu modelo devolver.
import hmac, os, queue, threading
import requests
from flask import Flask, abort, request
EC = "https://easycoexistence.com/api/v1"
KEY = {"Authorization": f"Bearer {os.environ['EC_API_KEY']}"} # ec_live_...
PATH_SECRET = os.environ["WA_PATH_SECRET"] # the random part of each webhook_url
CONNECTIONS: dict[str, str] = {} # phone_number_id -> connection id, from your database
jobs: queue.Queue = queue.Queue()
app = Flask(__name__)
@app.route("/wa/<secret>", methods=["GET", "POST"])
def whatsapp(secret: str):
if not hmac.compare_digest(secret, PATH_SECRET):
abort(404)
if request.method == "GET": # Meta's handshake when the destination is set
if request.args.get("hub.verify_token") != os.environ["WA_VERIFY_TOKEN"]:
abort(403)
return request.args.get("hub.challenge", "")
for entry in request.get_json().get("entry", []):
for change in entry.get("changes", []):
if change.get("field") == "messages": # echoes and history are context, not prompts
value = change["value"]
for msg in value.get("messages", []):
jobs.put((value["metadata"]["phone_number_id"], msg))
return "", 200 # answer at once; dedupe on msg["id"], since Meta can deliver twice
def worker() -> None:
while True:
phone_number_id, msg = jobs.get()
conn = requests.get(f"{EC}/connections/{CONNECTIONS[phone_number_id]}",
headers=KEY, params={"credentials": 1}).json()
creds = conn["credentials"]
if not creds["access_token"]: # token_ready is false: a new connect session issues one
continue
reply = my_model(conn["external_ref"], msg) # your model, your prompt, your memory
requests.post(creds["send_endpoint"], # a reply to a fresh message is inside the 24 hours
headers={"Authorization": f"Bearer {creds['access_token']}"},
json={"messaging_product": "whatsapp", "to": msg["from"],
"type": "text", "text": {"body": reply}})
threading.Thread(target=worker, daemon=True).start()Servidor MCP ou Partner API: qual usa o agente?
A Partner API, quando o agente é o seu produto e os clientes trazem os canais: o seu backend guarda a chave, recebe os eventos e executa o modelo que escolher. O servidor MCP em https://easycoexistence.com/api/mcp é indicado para um assistente como o Claude ou o ChatGPT a atuar na sua própria conta easyCoexistence, através de ferramentas que chama a pedido, após um início de sessão OAuth. Os números e canais ligados com a sua chave ficam também nessa conta, pelo que uma sessão MCP pode aceder-lhes para o trabalho da sua própria equipa.
| Partner API | MCP server | |
|---|---|---|
| Built for | Your product, serving your customers | An assistant working on your own account |
| Signs in with | An ec_live_ key, one per account | OAuth, from Claude, ChatGPT or another client |
| Incoming messages | Webhooks to your backend | Read when the assistant calls a tool |
| The model | Any model you run | The assistant's own |
| Replies | Your code calls each network's API | Tools such as send_message and reply_to_comment |
Como gerem as agências agentes para muitos clientes?
Numa só conta, com cada cliente identificado. Passe o ID do cliente como external_ref em cada sessão de ligação, mostre o nome da sua agência na página alojada com partner_name e liste as ligações de um cliente com GET /connections?external_ref= e GET /channels?external_ref=. Cada ligação é faturada à agência a US$ 9 até US$ 0,75 por ligação por mês, descendo à medida que se acrescentam ligações, enquanto a Meta fatura as cobranças de conversas do WhatsApp à conta WhatsApp Business do próprio cliente. Com a Coexistence, a equipa do cliente continua a responder na app WhatsApp Business, ao lado do agente.
Que regras tem o agente de cumprir?
As próprias das redes, que o seu código deve verificar antes de a resposta do modelo sair. As plataformas mantêm-nas em nome dos seus clientes, já que a fiscalização da Meta recai sobre a conta do cliente:
- WhatsApp: respostas de texto livre só dentro de 24 horas após a última mensagem do cliente; depois disso, um template aprovado, enviado através da API, porque a app WhatsApp Business não consegue enviar templates na Coexistence.
- WhatsApp: as regras da Meta proíbem oferecer IA como funcionalidade principal, o que a referência da Partner API descreve como ausência de chatbots de IA de uso geral, e permitem o ajuste fino com dados do WhatsApp apenas para uso exclusivo da empresa.
- Instagram e Facebook: mensagens diretas dentro de 24 horas após a última mensagem da pessoa, e uma resposta privada por comentário, no prazo de 7 dias a contar do comentário.
- TikTok: as respostas a comentários são públicas, já que uma ligação ao TikTok não tem mensagens diretas.
- Volume: 20 mensagens por segundo por número Coexistence, e os templates de marketing exigem um meio de pagamento na conta WhatsApp Business do cliente.
Como sabe o agente que um canal deixou de funcionar?
Através dos eventos de estado. connection.disconnected ou channel.disconnected significa que as respostas falham até que o cliente volte a ligar, pelo que deve pausar o agente desse cliente, avisá-lo e enviar um novo link de ligação. connection.token_missing significa que o número consegue receber, mas ainda não consegue enviar. Quando chegar de novo connection.connected ou channel.connected, obtenha credenciais novas e retome. Cada evento é assinado com X-EC-Signature e volta a ser enviado durante cerca de 33 horas.
Erros comuns
- Deixar o modelo responder com texto livre a uma mensagem do WhatsApp com mais de 24 horas. A janela já fechou, por isso verifique a hora da última mensagem recebida do cliente e passe para um template aprovado.
- Treinar um modelo partilhado com as conversas WhatsApp dos clientes. As regras da Meta permitem o ajuste fino com dados da WhatsApp Business Platform apenas para uso exclusivo da empresa, nunca para melhorar outros modelos.
- Tratar smb_message_echoes como mensagens dos clientes. São o que a equipa da empresa enviou a partir da app, por isso dê-os ao modelo como contexto, e não como mensagens a que responder.
- Responder às próprias respostas da conta. As mensagens diretas do Instagram que ela envia voltam como echoes e as respostas do TikTok voltam como eventos de comentário, por isso ignore tudo o que a própria conta escreveu, ou o agente responde a si mesmo.
US$ 9 até US$ 0,75 por ligação por mês, descendo à medida que acrescenta ligações, com os primeiros 3 dias gratuitos.
Perguntas frequentes
Posso usar o meu próprio modelo de IA?
Sim. O seu backend recebe as mensagens, chama o modelo que escolher e responde através da API da rede com o token do cliente. As mensagens de um número WhatsApp seguem da Meta diretamente para o seu webhook, sem passar pela easyCoexistence.
O que significa a política de IA da Meta para um agente no WhatsApp?
As regras da Meta proíbem os fornecedores de IA de usar a WhatsApp Business Platform para oferecer tecnologia de IA como funcionalidade principal, e não acessória ou complementar, conforme a Meta determinar. Cumpra-a em nome dos seus clientes, juntamente com a janela de 24 horas e os templates aprovados.
O agente pode enviar mensagens diretas no TikTok, YouTube ou LinkedIn?
Não. Nessas redes, o agente trabalha nos comentários: as respostas no TikTok são públicas, e os comentários do YouTube e do LinkedIn são lidos e respondidos através das respetivas APIs.
Quanto custa a easyCoexistence para um produto de agente de IA?
Por ligação, igual em todas as redes: US$ 9 até US$ 0,75 por ligação por mês, descendo à medida que acrescenta ligações, com os primeiros 3 dias gratuitos. A Meta fatura as cobranças de conversas do WhatsApp à conta WhatsApp Business de cada cliente.
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