LinkZap

Primeiros passos

.md

A API do LinkZap

Tudo o que a sua equipe faz na caixa — receber, responder, etiquetar, iniciar um fluxo — o seu sistema também pode fazer. E tudo o que acontece aqui pode chegar ao seu sistema no instante em que acontece.

São dois sentidos, e você vai usar os dois

A API é o que você chama: mandar uma mensagem quando um pedido é aprovado, cadastrar o lead que veio do formulário, ler a conversa para mostrar no seu CRM.

Os webhooks são o que nós chamamos: cada mensagem recebida, cada conversa resolvida, cada opt-out vira um POST assinado no endereço que você registrar. É o que evita ficar perguntando “tem novidade?” de minuto em minuto.

Existe ainda um terceiro caminho, o mais simples de todos: o webhook de entrada, uma URL por número que transforma um formulário de site, um Zapier ou um CRM em contato e conversa sem você escrever uma linha de código.

Três minutos até a primeira mensagem

  1. 1

    Crie uma chave

    No painel, Configurações → Integrações → Novo token. A chave começa com lz_ e aparece uma única vez — guarde-a onde você guarda as outras senhas do seu sistema. Se a perder, revogue e crie outra.

    Se o que você quer é uma chave que só fala por UM número, use Canais → Copiar chave de API. Ela é mais segura para integrações de terceiros: não alcança os outros números da conta.

  2. 2

    Confira que ela funciona

    A resposta diz de qual organização é a chave e qual é o escopo dela — é como você descobre, sem adivinhar, se colou a chave da conta ou a de um canal.

    Conferir a chavecurl
    curl https://linkzap.orion.moe/api/v1/me \
  -H "Authorization: Bearer lz_SUA_CHAVE"
  3. 3

    Descubra o seu channelId

    Quase toda escrita pede o número pelo qual falar. A lista traz também se ele está pronto para enviar — e, se não estiver, o motivo em palavras.

    Listar os números conectadoscurl
    curl https://linkzap.orion.moe/api/v1/channels \
  -H "Authorization: Bearer lz_SUA_CHAVE"
  4. 4

    Mande a mensagem

    Não precisa criar o contato nem a conversa antes: se o telefone é novo, os dois nascem aqui. A mensagem aparece na caixa da sua equipe creditada como API, como qualquer outra.

    Enviar uma mensagemcurl
    curl -X POST https://linkzap.orion.moe/api/v1/messages \
  -H "Authorization: Bearer lz_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "SEU_CHANNEL_ID",
    "phone": "5592999990000",
    "text": "Seu pedido #1234 saiu para entrega."
  }'
  5. 5

    Receba o que acontece

    Em Configurações → Integrações → Novo webhook, aponte para uma URL pública sua e escolha os eventos. A partir daí cada resposta do contato chega no seu servidor, assinada. Como verificar a assinatura está em Webhooks de saída.

Antes de começar, três coisas

O número precisa estar conectado

A API não conecta números — ela fala pelos que já estão. Se GET /channels devolver ready: false, o motivo está no campo reason, e é o mesmo motivo que o envio recusaria com 409.

Janela de 24 horas na conta oficial

Nos números conectados pela API oficial da Meta (provider: "cloud"), texto livre só sai se o contato falou com você nas últimas 24 horas. Fora disso, só um template aprovado — que hoje se envia pelo painel, pelo fluxo, pela sequência ou pela campanha. Números conectados por QR (provider: "web") não têm essa janela.

Opt-in não é burocracia

Mandar mensagem para quem não pediu é o caminho mais rápido para o número ser bloqueado — e no modo QR o número é seu. Registre o opt-in (optIn: true ao criar o contato) e respeite o opt-out no seu sistema também.