Primeiros Passos

Conceituacao

Este guia vai te levar do zero ate o envio da sua primeira mensagem no WhatsApp via Ogmma API. Em poucos minutos voce vai ter tudo funcionando.

Vamos passar por 4 etapas simples:

Criar sua conta
Gerar uma API Key
Conectar um canal WhatsApp
Enviar sua primeira mensagem

Bora la!

Passo 1: Criar sua Conta

Para comecar, voce precisa criar uma conta no Ogmma. O registro cria automaticamente sua conta de usuario e uma instituicao (empresa).

Metodo

POST https://oapi.ogmma.com.br/v1/auth/register

Key	Value
Content-Type	application/json

Atributos

Obrigatorios

Atributos	Tipo	Descricao
name	string	Nome completo do usuario
email	string	Email para login
password	string	Senha (minimo 8 caracteres)
institutionName	string	Nome da sua empresa/organizacao

Request Body

{
  "name": "João Silva",
  "email": "joao@minhaempresa.com.br",
  "password": "SenhaSegura123!",
  "institutionName": "Minha Empresa LTDA"
}

cURL

curl -X POST "https://oapi.ogmma.com.br/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "email": "joao@minhaempresa.com.br",
    "password": "SenhaSegura123!",
    "institutionName": "Minha Empresa LTDA"
  }'

Response

201 - Criado

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "64f8b2c3e1a2b3c4d5e6f7a8",
    "name": "João Silva",
    "email": "joao@minhaempresa.com.br"
  },
  "institution": {
    "id": "64f8b2c3e1a2b3c4d5e6f7a9",
    "name": "Minha Empresa LTDA"
  }
}

400 - Dados Invalidos

{
  "error": "Email já está em uso"
}

Dica

Guarde o token retornado -- voce vai precisar dele para criar sua API Key no proximo passo.

Passo 2: Criar uma API Key

Com sua conta criada, agora vamos gerar uma API Key. Ela sera usada para autenticar todas as suas chamadas a API.

Metodo

POST https://oapi.ogmma.com.br/v1/api-keys

Header

Key	Value
Authorization	Bearer {jwt-token}
Content-Type	application/json

Atributos

Obrigatorios

Atributos	Tipo	Descricao
name	string	Nome identificador da chave (ex: "Integracao ERP")

Opcionais

Atributos	Tipo	Descricao
permissions	string[]	Lista de permissoes da chave. Pelo menos uma permissao e obrigatoria.
expiresAt	string	Data de expiracao no formato ISO 8601. Se omitido, a chave nao expira.

Request Body

{
  "name": "Integracao ERP",
  "permissions": [
    "messages.send",
    "messages.read",
    "conversations.read",
    "contacts.read",
    "contacts.write"
  ]
}

cURL

curl -X POST "https://oapi.ogmma.com.br/v1/api-keys" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Integracao ERP",
    "permissions": ["messages.send", "messages.read", "conversations.read"]
  }'

Response

201 - Criado

{
  "id": "64f8b2c3e1a2b3c4d5e6f7b0",
  "name": "Integracao ERP",
  "key": "oapi_sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "prefix": "oapi_sk_live",
  "permissions": [
    "messages.send",
    "messages.read",
    "conversations.read"
  ],
  "createdAt": "2025-01-15T10:30:00.000Z"
}

Atencao

A chave completa (key) so e exibida uma unica vez no momento da criacao. Copie e guarde em local seguro. Depois disso, apenas o prefixo sera visivel.

Passo 3: Conectar um Canal WhatsApp

Agora vamos conectar seu numero WhatsApp. Voce vai criar um canal e escanear um QR Code, similar ao WhatsApp Web.

3.1 - Criar o Canal

Metodo

POST https://oapi.ogmma.com.br/v1/channels

Header

Key	Value
Authorization	Bearer {sua-api-key}
Content-Type	application/json

Atributos

Obrigatorios

Atributos	Tipo	Descricao
name	string	Nome identificador do canal (ex: "WhatsApp Comercial")
type	string	Tipo do canal: `WHATSAPP_BAILEYS` ou `WHATSAPP_WABA`

Request Body

{
  "name": "WhatsApp Comercial",
  "type": "WHATSAPP_BAILEYS"
}

cURL

curl -X POST "https://oapi.ogmma.com.br/v1/channels" \
  -H "Authorization: Bearer oapi_sk_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "WhatsApp Comercial",
    "type": "WHATSAPP_BAILEYS"
  }'

Response

201 - Criado

{
  "id": "64f8b2c3e1a2b3c4d5e6f7c1",
  "name": "WhatsApp Comercial",
  "type": "WHATSAPP_BAILEYS",
  "status": "DISCONNECTED",
  "createdAt": "2025-01-15T10:35:00.000Z"
}

3.2 - Conectar o Canal (QR Code)

Apos criar o canal, voce precisa inicia-lo para gerar o QR Code de conexao.

Metodo

POST https://oapi.ogmma.com.br/v1/channels/{channelId}/connect

Header

Key	Value
Authorization	Bearer {sua-api-key}

cURL

curl -X POST "https://oapi.ogmma.com.br/v1/channels/64f8b2c3e1a2b3c4d5e6f7c1/connect" \
  -H "Authorization: Bearer oapi_sk_live_a1b2c3d4e5f6..."

Response

200 - OK

{
  "status": "CONNECTING",
  "qrCode": "2@abc123def456...",
  "message": "Escaneie o QR Code com seu WhatsApp"
}

Como escanear o QR Code

Abra o WhatsApp no seu celular
Va em Configuracoes > Aparelhos conectados > Conectar um aparelho
Escaneie o QR Code retornado pela API
Aguarde a conexao ser estabelecida

O status do canal mudara para CONNECTED automaticamente apos o scan. Voce pode acompanhar via Webhook ou consultando o status do canal.

3.3 - Verificar Status da Conexao

Metodo

GET https://oapi.ogmma.com.br/v1/channels/{channelId}

cURL

curl -X GET "https://oapi.ogmma.com.br/v1/channels/64f8b2c3e1a2b3c4d5e6f7c1" \
  -H "Authorization: Bearer oapi_sk_live_a1b2c3d4e5f6..."

Response

200 - OK (Conectado)

{
  "id": "64f8b2c3e1a2b3c4d5e6f7c1",
  "name": "WhatsApp Comercial",
  "type": "WHATSAPP_BAILEYS",
  "status": "CONNECTED",
  "phoneNumber": "5511999999999",
  "connectedAt": "2025-01-15T10:36:00.000Z"
}

Passo 4: Enviar sua Primeira Mensagem

Canal conectado? Agora e a hora da verdade! Vamos enviar uma mensagem de texto.

Metodo

POST https://oapi.ogmma.com.br/v1/channels/{channelId}/messages/text

Header

Key	Value
Authorization	Bearer {sua-api-key}
Content-Type	application/json

Atributos

Obrigatorios

Atributos	Tipo	Descricao
to	string	Numero do destinatario com codigo do pais (ex: `5511999999999`)
text	string	Conteudo da mensagem

Request Body

{
  "to": "5511999999999",
  "text": "Ola! Esta e minha primeira mensagem enviada pela Ogmma API 🚀"
}

cURL

curl -X POST "https://oapi.ogmma.com.br/v1/channels/64f8b2c3e1a2b3c4d5e6f7c1/messages/text" \
  -H "Authorization: Bearer oapi_sk_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "text": "Ola! Esta e minha primeira mensagem enviada pela Ogmma API 🚀"
  }'

Response

202 - Aceito

{
  "success": true,
  "message": "Mensagem enfileirada para envio"
}

400 - Dados Invalidos

{
  "message": "Required",
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "path": "to",
      "message": "Required",
      "validation": "invalid_type"
    }
  ]
}

404 - Canal Nao Encontrado

{
  "message": "Canal nao encontrado",
  "code": "CHANNEL_NOT_FOUND"
}

Acompanhando o Envio

A API retorna 202 Accepted porque o envio e processado de forma assincrona. Para saber quando a mensagem foi realmente entregue, configure um Webhook.

Fluxo Completo

Sua API Key → POST /messages/.../text → 202 Accepted
                                            ↓
                              Worker processa e envia
                                            ↓
                              WhatsApp confirma entrega
                                            ↓
                         Webhook POST para sua URL:
                         {
                           "event": "message:sent",
                           "messageId": "MSG123...",
                           "status": "sent"
                         }

Outros Tipos de Mensagem

Alem de texto, voce pode enviar:

Tipo	Endpoint	Documentacao
Imagem	`POST .../messages/image`	Enviar Imagem
Video	`POST .../messages/video`	Enviar Video
Audio	`POST .../messages/audio`	Enviar Audio
Documento	`POST .../messages/document`	Enviar Documento
Contato	`POST .../messages/contact`	Enviar Contato
Template	`POST .../messages/template`	Enviar Template

Proximos Passos

Parabens! Voce acabou de enviar sua primeira mensagem. Agora explore:

Autenticacao -- Entenda API Keys, escopos e limites de requisicao
Enviar Imagem -- Envie mensagens com midia
Webhooks -- Receba notificacoes em tempo real
Envio em Massa -- Dispare mensagens para multiplos contatos
Sandbox -- Teste sem um numero real

Conceituacao​

Passo 1: Criar sua Conta​

Metodo​

Header​

Atributos​

Obrigatorios​

Request Body​

cURL​

Response​

201 - Criado​

400 - Dados Invalidos​

Passo 2: Criar uma API Key​

Metodo​

Header​

Atributos​

Obrigatorios​

Opcionais​

Request Body​

cURL​

Response​

201 - Criado​

Passo 3: Conectar um Canal WhatsApp​

3.1 - Criar o Canal​

Metodo​

Header​

Atributos​

Obrigatorios​

Request Body​

cURL​

Response​

201 - Criado​

3.2 - Conectar o Canal (QR Code)​

Metodo​

Header​

cURL​

Response​

200 - OK​

3.3 - Verificar Status da Conexao​

Metodo​

cURL​

Response​

200 - OK (Conectado)​

Passo 4: Enviar sua Primeira Mensagem​

Metodo​

Header​

Atributos​

Obrigatorios​

Request Body​

cURL​

Response​

202 - Aceito​

400 - Dados Invalidos​

404 - Canal Nao Encontrado​

Acompanhando o Envio​

Fluxo Completo​

Outros Tipos de Mensagem​

Proximos Passos​

Conceituacao

Passo 1: Criar sua Conta

Metodo

Header

Atributos

Obrigatorios

Request Body

cURL

Response

201 - Criado

400 - Dados Invalidos

Passo 2: Criar uma API Key

Metodo

Header

Atributos

Obrigatorios

Opcionais

Request Body

cURL

Response

201 - Criado

Passo 3: Conectar um Canal WhatsApp

3.1 - Criar o Canal

Metodo

Header

Atributos

Obrigatorios

Request Body

cURL

Response

201 - Criado

3.2 - Conectar o Canal (QR Code)

Metodo

Header

cURL

Response

200 - OK

3.3 - Verificar Status da Conexao

Metodo

cURL

Response

200 - OK (Conectado)

Passo 4: Enviar sua Primeira Mensagem

Metodo

Header

Atributos

Obrigatorios

Request Body

cURL

Response

202 - Aceito

400 - Dados Invalidos

404 - Canal Nao Encontrado

Acompanhando o Envio

Fluxo Completo

Outros Tipos de Mensagem

Proximos Passos