Enviar presença

POST

api

chat

presence

:instance

Enviar presença

curl --request POST \
  --url https://api.example.com/api/chat/presence/:instance \
  --header 'Content-Type: application/json' \
  --header 'token: <token>' \
  --data '
{
  "number": "<string>",
  "state": "<string>",
  "duration": 123
}
'

const options = {
  method: 'POST',
  headers: {token: '<token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({number: '<string>', state: '<string>', duration: 123})
};

fetch('https://api.example.com/api/chat/presence/:instance', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/api/chat/presence/:instance"

payload = {
    "number": "<string>",
    "state": "<string>",
    "duration": 123
}
headers = {
    "token": "<token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Auth: TokenAccount ou TokenInstance • Rate-limit: Global (100/min) • Idempotente: sim (efêmero) Emite indicador de presença (“digitando…”, “gravando áudio…”, ou pausa) para um chat. Ideal para simular interação realista antes de enviar uma mensagem.

Exemplos

Digitando 5s

Mostra o indicador “digitando…” no chat do destinatário e dispara pause automaticamente após 5 segundos (graças ao duration: 5). Ideal para preceder o envio de uma mensagem de texto.

curl -X POST "https://ryzeapi.cloud/api/chat/presence/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "state": "typing",
    "duration": 5
  }'

await fetch(`https://ryzeapi.cloud/api/chat/presence/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number:   "5511999999999",
    state:    "typing",
    duration: 5
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/chat/presence/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "number":   "5511999999999",
        "state":    "typing",
        "duration": 5
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "number": "5511999999999",
        "state": "typing",
        "duration": 5
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/chat/presence/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

Gravando áudio

Exibe “gravando áudio…” com state: "recording". Sem duration, o indicador permanece até o WhatsApp expirá-lo naturalmente (~5–10s) ou até você enviar pause manualmente.

curl -X POST "https://ryzeapi.cloud/api/chat/presence/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "state": "recording"
  }'

await fetch(`https://ryzeapi.cloud/api/chat/presence/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number: "5511999999999",
    state:  "recording"
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/chat/presence/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "number": "5511999999999",
        "state":  "recording"
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "number": "5511999999999",
        "state": "recording"
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/chat/presence/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

Cancelar indicador

Com state: "pause", encerra imediatamente qualquer indicador “digitando…” ou “gravando…” ativo no chat. Útil quando um fluxo automatizado termina antes do duration previsto.

curl -X POST "https://ryzeapi.cloud/api/chat/presence/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "state": "pause"
  }'

await fetch(`https://ryzeapi.cloud/api/chat/presence/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number: "5511999999999",
    state:  "pause"
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/chat/presence/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "number": "5511999999999",
        "state":  "pause"
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "number": "5511999999999",
        "state": "pause"
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/chat/presence/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

Resposta de sucesso

Com duração
Sem duração

200 OK

{
  "success": true,
  "message": "Presence 'typing' sent successfully (will auto-pause after 5 seconds)",
  "chat_jid": "5511999999999@s.whatsapp.net",
  "state": "typing",
  "duration": 5
}

200 OK

{
  "success": true,
  "message": "Presence 'typing' sent successfully",
  "chat_jid": "5511999999999@s.whatsapp.net",
  "state": "typing",
  "duration": 0
}

Path parameters

string

obrigatório

Nome da instância.

Headers

string

obrigatório

TokenAccount ou TokenInstance.

Request body

string

obrigatório

Número ou JID do chat.

string

obrigatório

typing / recording / pause / paused (case-insensitive).

int

padrão:"0"

Segundos até auto-pause (0–60). Quando >0 e state é typing/recording, a API envia pause automaticamente após esse intervalo. Ignorado em pause/paused.

Estados aceitos

`state`	Efeito
`typing`	”digitando…” no chat do destinatário
`recording`	”gravando áudio…”
`pause` / `paused`	Cancela qualquer indicador atual

Notas

Presenças são efêmeras, não persistem em banco e o WhatsApp expira o indicador no celular do destinatário em ~5–10s mesmo sem pause explícito.
duration > 60 é truncado para 60 (cap interno).
Em chats onde o destinatário desativou as confirmações de presença, o indicador pode não aparecer.

Respostas de erro

HTTP	`error.message`	Quando
400	`Invalid request body`	JSON malformado.
400	`Number is required`	Campo ausente.
400	`State is required. Use 'typing', 'recording', or 'pause'`	`state` vazio.
400	`Invalid state. Use 'typing', 'recording', or 'pause'`	Fora do enum.
401	`Invalid token`	,
404	`Instance not found`	,
503	`Instance is not connected to WhatsApp`	Sem sessão ativa.

Introdução

Instância

Eventos

Mensagens

Chamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidade

Enviar presença

Exemplos

Digitando 5s

Gravando áudio

Cancelar indicador

Resposta de sucesso

Path parameters

Headers

Request body

Estados aceitos

Notas

Respostas de erro

​Exemplos

​Digitando 5s

​Gravando áudio

​Cancelar indicador

​Resposta de sucesso

​Path parameters

​Headers

​Request body

​Estados aceitos

​Notas

​Respostas de erro

Exemplos

Digitando 5s

Gravando áudio

Cancelar indicador

Resposta de sucesso

Path parameters

Headers

Request body

Estados aceitos

Notas

Respostas de erro