Documentação da API

Autenticação

Todas as requisições exigem um Bearer token no header. O token está disponível em Meu Perfil no painel.

header

Authorization: Bearer orb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

URL base

base url

https://seu-dominio.com/api/instances/{uuid}

Enviar mensagem

POST /api/instances/{uuid}/send-text

Envia uma mensagem de texto. target aceita @username ou thread_id. A digitação é simulada com delays aleatórios.

Body (JSON)

Campo	Tipo	Obrigatório	Descrição
`target`	string		`@username` ou `thread_id`
`message`	string		Texto da mensagem

request

POST /api/instances/85be308d-.../send-text
Authorization: Bearer orb_xxxxxxxx...
Content-Type: application/json

{
  "target": "@usuario",
  "message": "Olá, tudo bem?"
}

200 OK

{
  "success": true,
  "message": null
}

500 Error

{
  "ok": false,
  "erro": "Falha ao enviar"
}

Listar conversas

GET /api/instances/{uuid}/conversas

Retorna as conversas visíveis no Direct inbox com nome, última mensagem, timestamps, status de leitura e presença online.

response 200

{
  "success": true,
  "conversas": [{
    "nome":            "João Silva",
    "ultima_mensagem": "Olá!",
    "tempo":           "Há 3 minutos",
    "tempo_curto":     "3 min",
    "nao_lido":        true,
    "online":          false,
    "foto_url":        "https://...",
    "username":        "@joaosilva",
    "thread_id":       "340282366841710300949128143467946586475"
  }]
}

Campos

Campo	Tipo	Descrição
`nome`	string	Nome de exibição do contato
`ultima_mensagem`	string	Preview da última mensagem
`tempo`	string	Ex: "Há 3 minutos"
`tempo_curto`	string	Ex: "3 min", "4 sem"
`nao_lido`	boolean	Mensagens não lidas
`online`	boolean	Presença online do contato
`foto_url`	string	URL da foto de perfil
`username`	string	@username do perfil
`thread_id`	string	ID único da conversa

Ler mensagens

GET /api/instances/{uuid}/mensagens

Retorna as mensagens visíveis de uma conversa. Requer thread_id ou username.

Query params

Param	Tipo	Descrição
`thread_id`	string	ID da conversa
`username`	string	@username do contato

response 200

{
  "success":   true,
  "thread_id": "340282366841710300949128143467946586475",
  "username":  "@joaosilva",
  "nome":      "João Silva",
  "mensagens": [
    { "texto": "Olá!", "hora": "21:03", "remetente": "contato", "username": "@joaosilva" },
    { "texto": "Tudo sim!", "hora": "21:04", "remetente": "eu", "username": "" }
  ]
}

Status

GET /api/instances/{uuid}/status

response 200

{ "ok": true, "status": "online" }

Webhook

Configure a URL de webhook ao criar ou editar a instância. Todos os eventos são enviados via POST com o payload abaixo.

payload

{
  "event":         "new_message",
  "instance_uuid": "1375020d-5c0d-4057-9df9-6bdf1a17653f",
  "instance_name": "Teste",
  "data": {
    "sender":    "ferreiradeivisonsilva",
    "sender_id": "18040138166557138",
    "thread_id": "1903609874362795",
    "message":   "Teste.",
    "from_me":   false
  }
}

Referência de eventos

Evento	Descrição	Campos em `data`
`new_message`	Nova mensagem recebida ou enviada via API	`sender`, `sender_id`, `thread_id`, `message`, `from_me`
`typing`	Contato começou a digitar	`name`, `username`, `thread_id`
`stopped_typing`	Contato parou de digitar	`name`, `username`, `thread_id`
`conversation_read`	Conversa foi lida	`name`, `username`, `thread_id`
`contact_online`	Contato ficou online	`name`, `username`, `thread_id`
`contact_offline`	Contato ficou offline	`name`, `username`, `thread_id`

Campos de `data`

Campo	Tipo	Descrição
`sender`	string	Username do remetente
`sender_id`	string	ID numérico do remetente
`thread_id`	string	ID da conversa
`message`	string	Conteúdo da mensagem
`from_me`	boolean	`true` se enviada pelo bot

WebSocket (Laravel Echo)

Os eventos também são transmitidos em tempo real via Laravel Echo. Canal por instância:

channel

instagram-instance.{uuid}

Mapeamento webhook → WebSocket

Webhook	Laravel Echo
`new_message`	`.InstagramNovaMensagem`
`typing`	`.InstagramDigitando`
`stopped_typing`	`.InstagramParouDigitar`
`conversation_read`	`.InstagramConversaLida`
`contact_online`	`.InstagramContatoOnline`
`contact_offline`	`.InstagramContatoOffline`

exemplo de uso

// Conectar ao canal da instância
window.Echo.channel(`instagram-instance.${uuid}`)
  .listen('.InstagramNovaMensagem', (e) => {
    console.log(e.sender, e.message, e.from_me);
  })
  .listen('.InstagramContatoOnline', (e) => {
    console.log(e.nome, 'ficou online');
  });

Códigos de erro

HTTP	Significado	Causa
`401`	Não autenticado	Token ausente ou inválido
`403`	Acesso negado	Instância pertence a outra conta
`404`	Não encontrado	UUID inválido ou instância removida
`422`	Dados inválidos	Campos obrigatórios ausentes ou malformados
`502`	Instância indisponível	Container parado ou reiniciando
`500`	Erro interno	Falha na execução do comando

Documentação

Autenticação

URL base

Enviar mensagem

Body (JSON)

Listar conversas

Campos

Ler mensagens

Query params

Status

Webhook

Referência de eventos

Campos de data

WebSocket (Laravel Echo)

Mapeamento webhook → WebSocket

Códigos de erro

Campos de `data`