Simular Mensagem de Entrada

Metodo

POST https://oapi.ogmma.com.br/v1/sandbox/simulate/incoming

Conceituacao

Simula o recebimento de uma mensagem enviada por um contato. Este endpoint permite testar seu fluxo de webhooks de ponta a ponta, sem precisar de um numero de WhatsApp real enviando mensagens.

Ao chamar este endpoint, a Ogmma simula internamente o recebimento de uma mensagem, disparando o evento message.received no webhook configurado. Isso permite validar que sua aplicacao esta processando corretamente as mensagens de entrada, incluindo:

• Criacao automatica de conversas
• Disparo de webhooks
• Acionamento de fluxos automatizados (chatbots, agentes de IA)
• Roteamento para departamentos

Fluxo da simulacao

Sua aplicacao → POST /api/sandbox/simulate/incoming
       ↓
Ogmma processa como mensagem real de entrada
       ↓
Webhook message.received e disparado
       ↓
Sua aplicacao recebe o webhook e processa

Atributos

Header

Atributo	Tipo	Obrigatorio	Descricao
Authorization	string	Sim	Bearer {API_KEY} - Chave de autenticacao da API (prefixo oapi_sk_test_)
Content-Type	string	Sim	application/json

Body

Atributo	Tipo	Obrigatorio	Descricao
from	string	Sim	Numero de telefone do remetente no formato internacional (ex: 5511988887777)
type	string	Sim	Tipo da mensagem. Valores: text, image, video, audio, document
content	object	Sim	Conteudo da mensagem. A estrutura varia conforme o type

Conteudo por tipo

Texto (type: "text"):

Atributo	Tipo	Obrigatorio	Descricao
content.text	string	Sim	Texto da mensagem recebida

Imagem (type: "image"):

Atributo	Tipo	Obrigatorio	Descricao
content.url	string	Sim	URL da imagem
content.caption	string	Nao	Legenda da imagem

Request

Exemplo com texto:

cURL

curl -X POST "https://oapi.ogmma.com.br/v1/sandbox/simulate/incoming" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "5511988887777",
    "type": "text",
    "content": {
      "text": "Ola, gostaria de saber sobre os planos disponiveis."
    }
  }'

Node.js

const axios = require('axios');

const response = await axios.post(
  'https://oapi.ogmma.com.br/v1/sandbox/simulate/incoming',
  {
    from: '5511988887777',
    type: 'text',
    content: {
      text: 'Ola, gostaria de saber sobre os planos disponiveis.'
    }
  },
  {
    headers: {
      'Authorization': 'Bearer {API_KEY}',
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.data);

Python

import requests

response = requests.post(
    'https://oapi.ogmma.com.br/v1/sandbox/simulate/incoming',
    json={
        'from': '5511988887777',
        'type': 'text',
        'content': {
            'text': 'Ola, gostaria de saber sobre os planos disponiveis.'
        }
    },
    headers={
        'Authorization': 'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }
)

print(response.json())

Exemplo com imagem:

cURL

curl -X POST "https://oapi.ogmma.com.br/v1/sandbox/simulate/incoming" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "5511988887777",
    "type": "image",
    "content": {
      "url": "https://exemplo.com/comprovante.jpg",
      "caption": "Segue o comprovante de pagamento"
    }
  }'

Node.js

const axios = require('axios');

const response = await axios.post(
  'https://oapi.ogmma.com.br/v1/sandbox/simulate/incoming',
  {
    from: '5511988887777',
    type: 'image',
    content: {
      url: 'https://exemplo.com/comprovante.jpg',
      caption: 'Segue o comprovante de pagamento'
    }
  },
  {
    headers: {
      'Authorization': 'Bearer {API_KEY}',
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.data);

Python

import requests

response = requests.post(
    'https://oapi.ogmma.com.br/v1/sandbox/simulate/incoming',
    json={
        'from': '5511988887777',
        'type': 'image',
        'content': {
            'url': 'https://exemplo.com/comprovante.jpg',
            'caption': 'Segue o comprovante de pagamento'
        }
    },
    headers={
        'Authorization': 'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }
)

print(response.json())

Response

200 - Mensagem simulada com sucesso

{
  "success": true,
  "data": {
    "messageId": "msg_sandbox_6650a1b2c3d4e5f6a7b8c9d2",
    "conversationId": "conv_6650a1b2c3d4e5f6a7b8c9d3",
    "from": "5511988887777",
    "type": "text",
    "content": {
      "text": "Ola, gostaria de saber sobre os planos disponiveis."
    },
    "status": "RECEIVED",
    "webhookFired": true
  }
}

400 - Dados invalidos

{
  "message": "Dados de entrada invalidos.",
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "path": "from",
      "message": "Numero de telefone e obrigatorio.",
      "validation": "invalid_type"
    }
  ]
}

400 - Endpoint exclusivo do sandbox

{
  "message": "Este endpoint esta disponivel apenas no ambiente sandbox. Utilize uma API key de teste.",
  "code": "SANDBOX_ONLY"
}

401 - Nao autorizado

{
  "message": "Token de autenticacao invalido ou ausente.",
  "code": "AUTHENTICATION_REQUIRED"
}

429 - Rate limit excedido

{
  "message": "Limite de requisicoes excedido. Tente novamente em alguns segundos.",
  "code": "RATE_LIMIT_EXCEEDED"
}

Dica

Use este endpoint em conjunto com a configuracao de webhooks para testar todo o ciclo de vida de uma mensagem recebida. Voce pode validar que seu servidor processa corretamente o evento message.received e responde adequadamente.