Pular para o conteúdo

Começar

Começar em 5 minutos

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

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

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

Janela do terminal
export MESSAJO_API_KEY="mj_..."

Detalhes em Autenticação e chaves de API.

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.

Janela do terminal
curl https://api.messajo.com/v1/me \
-H "Authorization: Bearer $MESSAJO_API_KEY"

Resposta 200 OK:

{
"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 (faltou o cabeçalho) ou invalid_api_key (chave errada ou revogada).

  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.

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

Janela do terminal
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." }
}'

O SDK gera o Idempotency-Key sozinho e repete com segurança quando a rede falha. Veja SDK TypeScript.

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.

Janela do terminal
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á!" } }'

Veja Tipos de chave.

A resposta é 201:

{
"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. Cada tipo tem a sua página no grupo Enviar mensagens, a começar por Enviar texto; os campos de cada um estão também na referência da API.

  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.
{
"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. O catálogo completo está em Eventos.