> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brainchat.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Encurtador de URL

> Gere links curtos com token para usar em botões URL dinâmicos de templates WhatsApp (contorna a limitação de 1 variável da Meta).

A Meta permite **apenas 1 variável** em botões URL de template, obrigatoriamente como **sufixo puro** (sem `?`, `=`, `&` ou `#`). Quando você precisa passar múltiplos parâmetros dinâmicos (ex: `?contratante=…&vincular_vaga=…`), use o encurtador:

1. Cadastre o template Meta com botão URL apontando para `https://brainchat.app/r/{{1}}`.
2. Antes de enviar cada mensagem, chame `create-short-link` com a **URL final** (com todos os parâmetros).
3. Envie o template passando **apenas o token** retornado em `button_1`.

Quando o cliente clica, o encurtador faz `302` para a URL final.

***

## Criar um link curto

```
POST https://wapi.stegia.com.br/functions/v1/create-short-link
```

### Headers

| Header | Valor |
| - | - |
| `Content-Type` | `application/json` |
| `X-Client-Token` | Seu token do canal (veja [Autenticação](https://docs.brainchat.app/api/autenticacao.md)) |

### Body

| Campo | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `targetUrl` | string | ✅ | URL completa (http/https) para onde o cliente será redirecionado |
| `instanceId` | string | ⚠️ | ID do canal. Opcional se o `X-Client-Token` estiver vinculado a um único canal |
| `expiresIn` | number | ❌ | Validade em **minutos** (default: sem expiração) |
| `maxHits` | number | ❌ | Limite de acessos (default: ilimitado) |

### Exemplo

```bash theme={null}
curl -X POST "https://wapi.stegia.com.br/functions/v1/create-short-link" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN_AQUI" \
  -d '{
    "instanceId": "5f9ae3c9-c863-4972-9eb7-7e1962f19c3c",
    "targetUrl": "https://app.pipefy.com/public/form/AIbgrOi4?contratante=1346452978&vincular_vaga=1409608130"
  }'
```

### Resposta (200)

```json theme={null}
{
  "success": true,
  "token": "x7k9m2a",
  "shortUrl": "https://brainchat.app/r/x7k9m2a",
  "expiresAt": null
}
```

### Erros

| Status | `error` | Quando ocorre |
| - | - | - |
| 400 | `invalid_target_url` | `targetUrl` ausente ou não é http/https absoluto |
| 400 | `instance_not_resolved` | Não foi possível identificar o canal |
| 400 | `invalid_expires_in` / `invalid_max_hits` | Valores inválidos |
| 401 | `missing_client_token` | Header `X-Client-Token` ausente |

***

## Usar em templates

Depois de criar o link, envie o template passando o **token puro** no `button_1`:

```bash theme={null}
curl -X POST "https://wapi.stegia.com.br/functions/v1/send-template-message" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN_AQUI" \
  -d '{
    "templateId": "57660f84-6671-4d07-9c29-70d56c341045",
    "instanceId": "5f9ae3c9-c863-4972-9eb7-7e1962f19c3c",
    "phone": "5522997175635",
    "variables": {
      "nome": "Hygor",
      "button_1": "x7k9m2a",
      "nome_vaga": "AUXILIAR DE SERVIÇOS GERAIS"
    }
  }'
```

A Meta recebe `https://brainchat.app/r/x7k9m2a` — 1 variável, sufixo puro, sem caracteres proibidos.

> [!NOTE]
>
> Ao chamar `send-template-message` diretamente com um `button_1` contendo `?`, `=` ou `&`, o endpoint continua bloqueando com `template_button_url_parameter_invalid`. Use o encurtador para contornar.

***

## Fluxo em automações

```text theme={null}
1. (Passo A) POST /create-short-link
             body: { targetUrl: "https://app.pipefy.com/public/form/...?contratante=…&vincular_vaga=…" }
             → { token: "x7k9m2a", shortUrl: "https://brainchat.app/r/x7k9m2a" }

2. (Passo B) POST /send-template-message
             body: { ..., variables: { button_1: "x7k9m2a", ... } }
             → mensagem enviada com botão https://brainchat.app/r/x7k9m2a

3. Cliente clica → 302 → URL final com todos os parâmetros
```

***

## Detalhes

* **Token**: 7 caracteres alfanuméricos aleatórios (\~34 bilhões de combinações).
* **Escopo**: cada token pertence a um canal. Só o dono do canal (ou admin) enxerga/gerencia seus links.
* **Contagem de acessos**: cada redirect incrementa `hit_count` e atualiza `last_hit_at` (best-effort).
* **Sem cache**: a resposta 302 é enviada com `Cache-Control: no-store`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.