# Começar em 5 minutos

> Da conta nova à primeira chamada da API e à primeira mensagem, passo a passo.

## Antes de começar

Você precisa de uma conta em `app.messajo.com`. Tenha também um terminal com `curl`.

Nos exemplos, a API fica em `https://api.messajo.com/v1`.

## 1. Criar a conta e a organização

1. Abra o painel e clique em **Criar conta**. Informe nome, e-mail e senha.
2. Confirme o e-mail pelo link que chega na sua caixa de entrada.
3. Dê um nome à sua organização. Você vira o **dono** dela.

Tudo no Messajo — conexões, chaves, destinos de eventos — pertence à organização, não à pessoa. Veja [Conceitos](/start/concepts/).

## 2. Ligar o 2FA

A verificação em duas etapas é obrigatória para dono e admin. Sem ela o painel não libera as áreas da organização, inclusive a criação de chaves.

1. Em **Configurações → Segurança**, ative a **Verificação em duas etapas (2FA)**.
2. Leia o QR code com um app autenticador (Google Authenticator, 1Password, Authy…) e digite o código de 6 dígitos.
3. Guarde os **códigos de backup** num lugar seguro: eles são a saída se você perder o celular.

## 3. Criar uma chave de API

1. Abra **Chaves de API** e clique em **Criar chave**.
2. Dê um nome (por exemplo, `teste`) e marque só a permissão **Ler** (`read`), que basta para este guia.
3. Deixe **Todas as conexões**, escolha a validade e confirme.

A chave completa, que começa com `mj_`, aparece **uma única vez**. Copie e guarde numa variável de ambiente:

```bash
export MESSAJO_API_KEY="mj_..."
```

Detalhes em [Autenticação e chaves de API](/api/authentication/).

## 4. Testar com GET /v1/me

`GET /v1/me` aceita qualquer chave válida e mostra a organização e a própria chave. É a forma mais rápida de confirmar que a autenticação está certa.

**cURL**

```bash
curl https://api.messajo.com/v1/me \
  -H "Authorization: Bearer $MESSAJO_API_KEY"
```

**TypeScript**

```ts
// npm install @messajo/sdk
import { Messajo } from "@messajo/sdk";

const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });
const me = await messajo.me.get();
console.log(me.organization.name, me.api_key.permissions);
```

**Python**

```python
import os

import requests

response = requests.get(
    "https://api.messajo.com/v1/me",
    headers={"Authorization": f"Bearer {os.environ['MESSAJO_API_KEY']}"},
    timeout=10,
)
response.raise_for_status()
me = response.json()
print(me["organization"]["name"], me["api_key"]["permissions"])
```

Resposta `200 OK`:

```json
{
  "organization": {
    "id": "Kq3vT9xZ2mWb7LpR4nYc8sDf1gHj6aEu",
    "name": "Acme",
    "slug": "acme"
  },
  "api_key": {
    "id": "Zt5rB8wQ1nXc4LmV7pYd2sGf9hJk3aRe",
    "name": "teste",
    "start": "mj_A1b2c3d",
    "permissions": ["read"],
    "connection_ids": null,
    "kind": "org",
    "connection_id": null,
    "connection": null,
    "expires_at": "2027-01-01T00:00:00.000Z"
  },
  "request_id": "req_0193a1b2c3d47e8f9a0b1c2d3e4f5a6b"
}
```

- `start` é o prefixo visível da chave, o mesmo que o painel mostra.
- `kind` é `org` (chave `mj_`) ou `connection` (chave `mjc_`). Em chave de conexão, `connection_id` e `connection { id, channel, label }` identificam a conexão dela; na de organização são `null`.
- `connection_ids: null` quer dizer que a chave de organização vale para todas as conexões; numa chave de conexão, traz só o id da conexão dela.
- `expires_at` é `null` quando a chave não expira.

Recebeu `401`? O corpo traz o `code` do erro, por exemplo [`missing_api_key`](/errors#missing_api_key) (faltou o cabeçalho) ou [`invalid_api_key`](/errors#invalid_api_key) (chave errada ou revogada).

## 5. Conectar um número de WhatsApp

1. No painel, abra **Conexões → Conectar WhatsApp**.
2. Escolha o modo: **Manter meu WhatsApp Business** (coexistência: o número continua no app) ou **Número novo, só pela API**, e clique em **Continuar**.
3. Clique em **Abrir o popup da Meta**, siga o cadastro oficial da Meta na janela que abre e espere o painel mostrar **WhatsApp conectado.**

A conexão aparece como **Ativa**, com um `id` no formato `conn_…`, usado nas chamadas de envio (a lista também sai em `GET /v1/connections`). O passo a passo completo está em [Conectar o WhatsApp](/connect/whatsapp/).

## 6. Enviar a primeira mensagem

Crie uma chave com a permissão `send` e chame `POST /v1/messages`. Mensagem livre só sai para um contato que falou com você nas últimas 24 horas; fora dessa janela, use um template aprovado (veja [Conceitos](/start/concepts/)).

**cURL**

```bash
curl https://api.messajo.com/v1/messages \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "connection_id": "conn_...",
    "to": "5511999999999",
    "type": "text",
    "text": { "body": "Olá! Mensagem enviada pelo Messajo." }
  }'
```

**TypeScript**

```ts
const sent = await messajo.messages.send({
  connection_id: "conn_...",
  to: "5511999999999",
  type: "text",
  text: { body: "Olá! Mensagem enviada pelo Messajo." },
});
```

**n8n**

n8n HTTP Request: POST https://api.messajo.com/v1/messages

```json
{
    "connection_id": "conn_...",
    "to": "5511999999999",
    "type": "text",
    "text": { "body": "Olá! Mensagem enviada pelo Messajo." }
  }
```

O SDK gera o `Idempotency-Key` sozinho e repete com segurança quando a rede falha. Veja [SDK TypeScript](/sdk/typescript/).

### Com chave de conexão

Se o código só fala com um número, crie uma **chave de conexão** (`mjc_…`) no painel da própria conexão, em **Chaves de API**. Ela já sabe a qual conexão pertence: o `connection_id` do corpo some, e a chave não alcança as outras conexões. Chave de organização (`mj_`) continua exigindo o `connection_id`.

**cURL**

```bash
curl https://api.messajo.com/v1/messages \
  -H "Authorization: Bearer $MESSAJO_CONNECTION_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "to": "5511999999999", "type": "text", "text": { "body": "Olá!" } }'
```

**TypeScript**

```ts
const sent = await messajo.connection().messages.send({
  to: "5511999999999",
  type: "text",
  text: { body: "Olá!" },
});
```

Veja [Tipos de chave](/api/authentication/#tipos-de-chave).

A resposta é `201`:

```json
{
  "id": "msg_...",
  "external_id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjQ",
  "status": "queued",
  "meta_status": "accepted",
  "conversation_id": "cnv_...",
  "contact_id": "ctc_...",
  "created_at": "2026-11-09T12:00:00.000Z"
}
```

`external_id` é o id da Meta (`wamid`). A entrega e a leitura chegam depois, no evento `message.status`. Fora da janela, a resposta é `422` [`outside_service_window`](/errors#outside_service_window). Cada tipo tem a sua página no grupo **Enviar mensagens**, a começar por [Enviar texto](/send/text/); os campos de cada um estão também na [referência da API](/reference).

## 7. Receber o webhook

1. Em **Destinos de eventos**, cadastre a URL HTTPS que vai receber os eventos. O painel mostra o segredo (`whsec_…`) uma vez.
2. Responda `2xx` em até 10 segundos. Sem isso, o Messajo tenta de novo com espera crescente por até 24 horas.
3. Mande uma mensagem para o seu número: chega um evento `message.received`.

```json
{
  "id": "evt_...",
  "type": "message.received",
  "format": "normalized",
  "org": "Kq3vT9xZ2mWb7LpR4nYc8sDf1gHj6aEu",
  "connection": "conn_...",
  "channel": "whatsapp",
  "timestamp": "2026-11-09T12:00:00.000Z",
  "sequence": 1,
  "data": {}
}
```

O conteúdo de `data` depende do tipo do evento e do formato do destino. Antes de confiar no corpo, confira o cabeçalho `Messajo-Signature` com o segredo: veja [Verificar a assinatura](/webhooks/verify-signature/). O catálogo completo está em [Eventos](/webhooks/events/).

## Próximos passos

- [Conceitos](/start/concepts/): organizações, conexões, chaves e as duas camadas da API.
- [Autenticação e chaves de API](/api/authentication/): permissões, validade e boas práticas.
- [Erros](/errors/) e [Limites](/api/limits/): o que tratar no seu código.
- [Verificar a assinatura](/webhooks/verify-signature/): obrigatório antes de ir para produção.
- [SDK TypeScript](/sdk/typescript/), [Histórico](/api/history/) e [Campanhas](/guides/campaigns/).
- [Enviar texto](/send/text/): a primeira de uma página por tipo de mensagem.
- [Construir com IA](/start/build-with-ai/): `llms.txt`, Markdown por página e o OpenAPI.
