EntrarComeçar teste grátis
easyCoexistence APIs oficiais

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 se apoia em três peças: um link de conexão hospedado para cada número de WhatsApp ou conta social do cliente; webhooks que levam as mensagens e comentários dele ao seu backend, onde o seu próprio modelo escreve as respostas, enviadas pela API oficial de cada rede com o token do cliente; e eventos de status para conexões que caem. O agente respeita as regras de cada rede, como a janela de 24 horas do WhatsApp.

O easyCoexistence dá aos agentes de IA do seu produto uma voz nos números de WhatsApp dos seus clientes e nas contas deles no Instagram, Facebook, TikTok, YouTube e LinkedIn, com novas redes chegando: links de conexão hospedados, credenciais sempre atualizadas, webhooks e eventos de status assinados pela API oficial de cada rede, com cada conexão monitorada 24/7.

24 hours

Janela de atendimento do WhatsApp após a mensagem ou ligação de um usuário; cada nova mensagem a reinicia.

Templates only

O que uma empresa no WhatsApp pode enviar depois que a janela de atendimento do cliente se fecha: mensagens de template pré-aprovadas.

Section 4.7

Os termos da Meta proíbem que provedores de IA usem o WhatsApp para oferecer IA como funcionalidade principal, e não incidental.

7 days

Janela para a resposta privada única a um comentário em uma conta do Instagram, contada a partir do momento em que o comentário foi feito.

20 mps

Throughput fixo de um número usado tanto com o app do WhatsApp Business quanto com a Cloud API.

De que um produto de agente de IA precisa no canal de cada cliente?

Quatro coisas: uma forma de o cliente conectá-lo, as mensagens dele chegando ao seu backend, um token para responder e um aviso quando a conexão parar de funcionar. A Partner API cobre cada uma delas, enquanto o modelo, os prompts e a lógica da conversa continuam com você. O easyCoexistence conecta a conta, mantém o acesso renovado e a monitora, e suas respostas saem do seu backend direto para a API da rede.

1ConnectA hosted link per customer: POST /connect-sessions
2ReceiveMessages from Meta; comments and DMs forwarded, signed
3DecideYour model, your prompts, your memory
4ReplyThe network's API, with the customer's token
5Watchconnection.* and channel.* status events

Como cada cliente se conecta?

Seu backend cria uma sessão de conexão com POST /connect-sessions, informando o canal, um redirect_url e um external_ref para o seu cliente e, para um número, o webhook_url e o webhook_verify_token. O cliente abre o link hospedado, entra com Meta, TikTok, Google ou LinkedIn e volta ao seu app com connection_id ou channel_id. Ele não precisa de conta, e-mail ou cartão no easyCoexistence, e toda conexão feita com a sua chave pertence à sua conta.

Como mensagens e comentários chegam ao seu modelo?

Por webhook, nas redes que os enviam. A Meta entrega as mensagens de um número direto no webhook_url, e o que a equipe da empresa envia pelo app do WhatsApp Business chega ali como smb_message_echoes. Comentários, menções e DMs do Instagram e do Facebook, além de comentários do TikTok, são encaminhados ao destino de cada canal, assinados com o secret do canal. YouTube e LinkedIn não enviam eventos de comentário, então o agente lê os novos comentários pelas APIs deles em uma agenda. Responda a cada entrega com 2xx imediatamente e deixe um worker chamar o modelo.

Como o agente responde?

Pela API própria da rede, com as credenciais que o seu backend buscou. Uma resposta no WhatsApp é um POST ao send_endpoint do número com o token do cliente; uma DM do Instagram ou do Facebook vai para o edge messages da conta; uma resposta no TikTok vai abaixo do comentário pelo business/comment/reply/create/. O esboço abaixo responde mensagens do WhatsApp: verifica o secret no caminho da URL, enfileira cada mensagem recebida e responde com o que o seu modelo devolver.

Python: a WhatsApp agent on your own model
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 o agente usa?

A Partner API, quando o agente é o seu produto e os seus clientes trazem os canais: o seu backend guarda a chave, recebe os eventos e roda qualquer modelo que você escolher. O servidor MCP em https://easycoexistence.com/api/mcp serve a um assistente como Claude ou ChatGPT atuando na sua própria conta do easyCoexistence, por meio de ferramentas que ele chama sob demanda, após um login OAuth. Números e canais conectados com a sua chave também ficam nessa conta, então uma sessão MCP pode acessá-los para o trabalho da sua própria equipe.

Partner APIMCP server
Built forYour product, serving your customersAn assistant working on your own account
Signs in withAn ec_live_ key, one per accountOAuth, from Claude, ChatGPT or another client
Incoming messagesWebhooks to your backendRead when the assistant calls a tool
The modelAny model you runThe assistant's own
RepliesYour code calls each network's APITools such as send_message and reply_to_comment

Como as agências rodam agentes para muitos clientes?

Em uma só conta, com cada cliente marcado. Passe o ID do cliente como external_ref em cada sessão de conexão, mostre o nome da sua agência na página hospedada com partner_name e liste as conexões de um cliente com GET /connections?external_ref= e GET /channels?external_ref=. Cada conexão é cobrada da agência de US$ 9 a US$ 0.75 por conexão por mês, caindo conforme as conexões são adicionadas, enquanto a Meta cobra as cobranças de conversa do WhatsApp na Conta do WhatsApp Business do próprio cliente. Com a Coexistência, a equipe do cliente continua respondendo no app do WhatsApp Business ao lado do agente.

Quais regras o agente precisa seguir?

As das próprias redes, que o seu código deve verificar antes que a resposta do modelo seja enviada. As plataformas as mantêm em nome dos clientes, já que a fiscalização da Meta recai sobre a conta do cliente:

  • WhatsApp: respostas de texto livre somente dentro de 24 horas da última mensagem do cliente; depois disso, um template aprovado, enviado pela API, porque o app do WhatsApp Business não pode enviar templates no modo Coexistência.
  • WhatsApp: os termos da Meta proíbem oferecer IA como funcionalidade principal, o que a referência da Partner API traduz como sem bots de IA de uso geral, e permitem o fine-tuning com dados do WhatsApp apenas para uso exclusivo da empresa.
  • Instagram e Facebook: DMs dentro de 24 horas da última mensagem da pessoa, e uma resposta privada por comentário em até 7 dias a partir dele.
  • TikTok: as respostas a comentários são públicas, já que uma conexão com o TikTok não tem DMs.
  • Volume: 20 mensagens por segundo por número de Coexistência, e templates de marketing exigem um método de pagamento na Conta do WhatsApp Business do cliente.

Como o agente sabe que um canal parou de funcionar?

Pelos eventos de status. connection.disconnected ou channel.disconnected significa que as respostas falham até o cliente reconectar, então pause o agente desse cliente, avise-o e envie um novo link de conexão; connection.token_missing significa que o número consegue receber, mas ainda não consegue enviar. Quando connection.connected ou channel.connected chegar de novo, busque credenciais novas e retome. Cada evento é assinado com X-EC-Signature e repetido por 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, então verifique a hora da última mensagem recebida do cliente e mude para um template aprovado.
  • Treinar um modelo compartilhado com as conversas de WhatsApp dos clientes. Os termos da Meta permitem o fine-tuning com dados da WhatsApp Business Platform apenas para uso exclusivo da empresa, nunca para melhorar outros modelos.
  • Tratar smb_message_echoes como mensagens de clientes. São o que a equipe da empresa enviou pelo app, então entregue-as ao modelo como contexto, não como mensagens a responder.
  • Responder às próprias respostas da conta. As DMs do Instagram que ela envia voltam como echoes e as respostas do TikTok como eventos de comentário, então ignore tudo que a própria conta escreveu, senão o agente responde a si mesmo.
Fazendo isso com o EasyCoexistence

De US$ 9 a US$ 0.75 por conexão por mês, caindo conforme você adiciona conexões, com os 3 primeiros 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

Posso usar meu próprio modelo de IA?

Sim. Seu backend recebe as mensagens, chama qualquer modelo que você escolher e responde pela API da rede com o token do cliente. As mensagens de um número de WhatsApp vão da Meta direto para o seu webhook, nunca passando pelo easyCoexistence.

O que a política de IA da Meta significa para um agente no WhatsApp?

Os termos da Meta proíbem que provedores de IA usem a WhatsApp Business Platform para oferecer tecnologia de IA como funcionalidade principal, e não incidental ou acessória, conforme determinado pela Meta. Cumpra isso em nome dos seus clientes, junto com a janela de 24 horas e os templates aprovados.

O agente pode enviar DMs no TikTok, YouTube ou LinkedIn?

Não. Nessas redes o agente atua nos comentários: as respostas do TikTok são públicas, e os comentários do YouTube e do LinkedIn são lidos e respondidos pelas APIs deles.

Quanto custa o easyCoexistence para um produto de agente de IA?

Por conexão, igual em todas as redes: de US$ 9 a US$ 0.75 por conexão por mês, caindo conforme você adiciona conexões, com os 3 primeiros dias grátis. A Meta cobra as cobranças de conversa do WhatsApp na Conta do WhatsApp Business de cada cliente.

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