Começar
Começar em 5 minutos
Da conta nova à primeira chamada da API e à primeira mensagem, passo a passo.
Antes de começar
Seção intitulada “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
Seção intitulada “1. Criar a conta e a organização”- Abra o painel e clique em Criar conta. Informe nome, e-mail e senha.
- Confirme o e-mail pelo link que chega na sua caixa de entrada.
- 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.
2. Ligar o 2FA
Seção intitulada “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.
- Em Configurações → Segurança, ative a Verificação em duas etapas (2FA).
- Leia o QR code com um app autenticador (Google Authenticator, 1Password, Authy…) e digite o código de 6 dígitos.
- 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
Seção intitulada “3. Criar uma chave de API”- Abra Chaves de API e clique em Criar chave.
- Dê um nome (por exemplo,
teste) e marque só a permissão Ler (read), que basta para este guia. - 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:
export MESSAJO_API_KEY="mj_..."Detalhes em Autenticação e chaves de API.
4. Testar com GET /v1/me
Seção intitulada “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 https://api.messajo.com/v1/me \ -H "Authorization: Bearer $MESSAJO_API_KEY"// npm install @messajo/sdkimport { 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);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:
{ "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(chavemj_) ouconnection(chavemjc_). Em chave de conexão,connection_ideconnection { id, channel, label }identificam a conexão dela; na de organização sãonull.connection_ids: nullquer 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énullquando 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).
5. Conectar um número de WhatsApp
Seção intitulada “5. Conectar um número de WhatsApp”- No painel, abra Conexões → Conectar WhatsApp.
- 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.
- 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.
6. Enviar a primeira mensagem
Seção intitulada “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).
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." } }'const sent = await messajo.messages.send({ connection_id: "conn_...", to: "5511999999999", type: "text", text: { body: "Olá! Mensagem enviada pelo Messajo." },});Configurações do nó HTTP Request do n8n
- Método:
POST - URL:
https://api.messajo.com/v1/messages - Autenticação: Generic Credential Type, depois Header Auth. Nome:
Authorization; Valor:Bearer mj_... - Cabeçalhos: ative Send Headers e adicione
Idempotency-Key(um valor único por item) - Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON
{ "connection_id": "conn_...", "to": "5511999999999", "type": "text", "text": { "body": "Olá! Mensagem enviada pelo Messajo." }}Substitua mj_... pela sua chave de API.
O SDK gera o Idempotency-Key sozinho e repete com segurança quando a rede falha. Veja SDK TypeScript.
Com chave de conexão
Seção intitulada “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 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á!" } }'const sent = await messajo.connection().messages.send({ 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.
7. Receber o webhook
Seção intitulada “7. Receber o webhook”- Em Destinos de eventos, cadastre a URL HTTPS que vai receber os eventos. O painel mostra o segredo (
whsec_…) uma vez. - Responda
2xxem até 10 segundos. Sem isso, o Messajo tenta de novo com espera crescente por até 24 horas. - 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.
Próximos passos
Seção intitulada “Próximos passos”- Conceitos: organizações, conexões, chaves e as duas camadas da API.
- Autenticação e chaves de API: permissões, validade e boas práticas.
- Erros e Limites: o que tratar no seu código.
- Verificar a assinatura: obrigatório antes de ir para produção.
- SDK TypeScript, Histórico e Campanhas.
- Enviar texto: a primeira de uma página por tipo de mensagem.
- Construir com IA:
llms.txt, Markdown por página e o OpenAPI.