---
title: "Começar"
slug: start
group: "Primeiros passos"
source: https://linkzap.orion.moe/developers/start
openapi: https://linkzap.orion.moe/openapi.json
---

# 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](https://linkzap.orion.moe/developers/inbound-webhook.md), 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. 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. 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.

Comando — Conferir a chave:

```bash
curl https://linkzap.orion.moe/api/v1/me \
  -H "Authorization: Bearer lz_SUA_CHAVE"
```

### 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.

Comando — Listar os números conectados:

```bash
curl https://linkzap.orion.moe/api/v1/channels \
  -H "Authorization: Bearer lz_SUA_CHAVE"
```

### 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.

Comando — Enviar uma mensagem:

```bash
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. 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](https://linkzap.orion.moe/developers/webhooks.md).

## Antes de começar, três coisas

> [!WARNING]
> **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.

> [!WARNING]
> **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.

> [!CAUTION]
> **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.