Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt

Use this file to discover all available pages before exploring further.

Auth: TokenAccount ou TokenInstance • Rate-limit: Global (100/min) • Idempotente: não O módulo /api/message/* cobre o envio de todos os formatos suportados pelo WhatsApp, texto, mídias, sticker, localização, contato, reação, enquete, carrossel, botões, lista, formulário, PIX e status (stories). Todas as rotas validam ownership da instância e aceitam TokenAccount ou TokenInstance.
Para buscar uma mensagem por ID use GET /api/chat/getMessage/:instance, esse endpoint deixou de pertencer ao módulo de mensagens.

​
Endpoints disponíveis

MétodoPathTipo
POST/api/message/text/:instanceTexto
POST/api/message/media/:instanceImagem / vídeo / áudio / documento
POST/api/message/sticker/:instanceSticker (WebP)
POST/api/message/location/:instanceLocalização
POST/api/message/contact/:instanceContato (vCard)
POST/api/message/reaction/:instanceReação (emoji)
POST/api/message/poll/:instanceEnquete
POST/api/message/carousel/:instanceCarrossel de cards
POST/api/message/button/:instanceBotões interativos
POST/api/message/list/:instanceLista (sections)
POST/api/message/form/:instanceFormulário (Native Flow)
POST/api/message/pix/:instancePIX (pagamento BR)
POST/api/message/status/:instanceStatus (stories)

​
Estrutura comum

​
Destinatário (number ou to)

A maioria dos endpoints aceita o destinatário no campo number. Os formatos suportados são:
  • Número simples: "5511999999999" (preferido).
  • JID privado: "5511999999999@s.whatsapp.net".
  • JID oculto (@lid): "123456789012345@lid", identificador anônimo usado pelo WhatsApp em grupos/canais quando o número real não está exposto.
  • JID grupo: "120363406289005073@g.us".
  • JID newsletter: "120363422585881117@newsletter".
  • Status broadcast: "status@broadcast".

​
Comportamento brasileiro do número

Para números começando com 55 (Brasil), o serviço tenta automaticamente variações:
  • Com 9 (5511999999999)
  • Sem 9 (551199999999)
Isso resolve um histórico de inconsistências em DDDs antigos. Se o número não for encontrado em nenhuma das variações, o handler retorna 400 Number is not registered on WhatsApp.

​
Campos opcionais comuns

CampoTipoAplica-se aDescrição
delayint (segundos)quase todosTempo de espera antes do envio. Durante o intervalo o servidor envia “digitando…” e depois “paused”.
replyTostringquase todosID da mensagem original a citar. A mensagem precisa pertencer à mesma instância e estar no banco.
replyPrivateboolquase todosQuando a mensagem citada é de grupo, redireciona a resposta para o privado do autor (mantém a citação).
mentionstring[]text / mediaNúmeros (ou JIDs) a mencionar. Apenas em grupos. Limite de 10 por mensagem.
mentionAllbooltext / mediaMenciona todos os membros do grupo (@todos). Apenas em grupos.
linkPreviewbooltextQuando true, busca metadados Open Graph da 1ª URL e envia como ExtendedTextMessage com card. Default false.
sourcestringtodosIdentificador de origem para rastreabilidade (ex.: crm, n8n). Default: "api".
delay é em segundos (não milissegundos). Valor 3 = 3 s de “digitando”.
Reactions (/api/message/reaction/:instance) não suportam delay/replyTo/mention, o payload é mínimo (messageId, reaction, participant). Status (/api/message/status/:instance) também não usa number/replyTo (sempre vai para status@broadcast).

​
Resposta padrão (200)

Todos os endpoints de envio retornam o mesmo envelope MessageSentDetails: 
{
  "success": true,
  "message": "Message sent successfully",
  "status":  "sent",
  "data": {
    "messageId":   "3EB08FCF27E532F1B0F5",
    "direction":   "outgoing",
    "messageType": "text",
    "content":     "Ola!",
    "source":      "api",
    "timestamp":   "2026-04-30T14:30:00Z",
    "chat": {
      "jid":     "5511999999999@s.whatsapp.net",
      "isGroup": false
    },
    "sender": {
      "jid":      "5511777777777@s.whatsapp.net",
      "instance": "minha-instancia"
    }
  }
}
Campos opcionais no data: mentions (quando há menção), replyTo (quando há citação), chat.groupName (quando é grupo), mediaUrl/mediaMimeType/mediaSize/fileName (quando é mídia), vcard (quando é contato). status ∈ sent | disconnected | invalid_number | mentions_not_supported | reply_message_not_found | reply_message_instance_mismatch | private_reply_failed | send_failed | media_download_failed | media_upload_failed | media_validation_failed | unsupported_media_type | image_conversion_failed | sticker_upload_failed | audio_conversion_failed | invalid_message_id | missing_participant | invalid_request.

​
Erros comuns

StatusMensagem
400Instance name is required
400Invalid request body: <detalhe>
400Number is required
400Message is required (e variantes por endpoint: MediaURL is required, Question is required, etc.)
400Mentions are only supported in group chats
400Original message not found (ID: ...)
400Original message does not belong to this instance
404Instance not found
503Instance is not connected to WhatsApp
500Failed to send message: <reason>
Envelope de erro: 
{
  "success": false,
  "error": { "message": "Number is not registered on WhatsApp" }
}

​
Limites observados

RecursoLimite
Texto~65k caracteres (mensagens > 4096 podem ser cortadas em alguns clients)
Imagem / vídeo / áudioaté 16 MB
Documentoaté 100 MB
Botõesmáx 3 por mensagem
Listamáx 10 sections × 10 rows
Carrosselmáx 10 cards
Enquete2 a 12 opções

​
Próximos passos

Enviar texto

Endpoint mais usado, ideal como “Hello World”.

Enviar mídia

Imagem, vídeo, áudio e documento por URL ou base64.

Buscar mensagem por ID

Recupera uma mensagem específica do histórico.

Webhooks

Recebe eventos message.exchange em tempo real.