Webhook de entrada

Uma URL por número: qualquer sistema que saiba fazer um POST — formulário de site, CRM, Zapier, Make, n8n — vira contato, mensagem e fluxo aqui dentro, sem você escrever código.

Onde pegar a URL e a chave

No painel, Canais: cada número tem a própria URL de webhook e o próprio botão Copiar chave de API. Os dois andam juntos — a chave do canal é a que abre aquela URL.

O formato da URLTexto

https://linkzap.orion.moe/api/webhooks/channel/SEU_CHANNEL_ID

Abrir essa URL no navegador (um GET) devolve o contrato em JSON — útil para conferir que copiou a URL certa.

O que mandar

POST/api/v1/channel/{id}

Cria ou atualiza o contato pelo telefone e, se pedido, manda a mensagem ou inicia o fluxo — tudo num POST.

Corpo (JSON)

phonetextoobrigatório
DDI + DDD + número.
nametexto
Nome do contato.
emailtexto
E-mail válido.
messagetexto
Um texto para enviar ao contato pelo canal. Use ou isto ou flowId, nunca os dois.
flowIdtexto
Em vez de texto: inicia este fluxo na conversa do contato.
tagslista
Até 20 etiquetas; as que não existem são criadas. Podem disparar um fluxo por si sós.
fieldsobjeto
Campos próprios seus (origem, número do pedido, o que fizer sentido).
optInbooleano
Registra o consentimento — marque só se a pessoa de fato autorizou.

Pedidocurl

curl -X POST https://linkzap.orion.moe/api/webhooks/channel/SEU_CHANNEL_ID \
  -H "x-api-key: lz_CHAVE_DO_CANAL" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5592999990000",
    "name": "Maria Souza",
    "message": "Oi, Maria! Recebemos o seu pedido de contato. Em que posso ajudar?",
    "tags": ["lead-site"],
    "fields": { "origem": "formulario-contato" },
    "optIn": true
  }'

RespostaJSON

{
  "data": {
    "contactId": "ctt_3c81...",
    "created": true,
    "channelId": "chn_9f2a...",
    "conversationId": "cnv_5ad2...",
    "messageId": "msg_7bd0..."
  }
}

O que volta

201 — criou o contato, ou enviou a mensagem, ou iniciou o fluxo.
200 — só num caso: o contato já existia e você não pediu mensagem nem fluxo.
403 — a chave é de outro canal.
409 — o número não está pronto para enviar. O contato foi salvo mesmo assim; só a mensagem não saiu.
503 — este servidor está sem a conexão de sistema; o webhook fica indisponível até alguém configurá-la.

Os campos de data dependem do que você pediu: sempre contactId, created e channelId; mais conversationId e messageId quando houve mensagem; mais conversationId e flow: "started" quando houve fluxo.

Quando usar este, e quando usar a API

Este webhook é um atalho: faz num POST o que seriam duas ou três chamadas da API (criar contato, garantir conversa, enviar ou iniciar fluxo). Use-o quando quem chama é uma ferramenta sem código — um formulário, um automatizador, um gatilho do seu CRM.

Quando quem chama é o seu backend, prefira a API: ela devolve mais informação, separa as responsabilidades e não obriga a mandar contato e mensagem no mesmo pacote.

Não é o webhook que te avisa

Este é o que você chama. Para receber aqui o que acontece lá — mensagem do contato, conversa resolvida —, o que você quer é a outra página: Webhooks de saída.