Enviar presencia

POST

api

chat

presence

:instance

Enviar presencia

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 o TokenInstance • Rate-limit: Global (100/min) • Idempotente: sí (efímero) Emite un indicador de presencia (“escribiendo…”, “grabando audio…” o pausa) hacia un chat. Ideal para simular interacción realista antes de enviar un mensaje.

Ejemplos

Escribiendo por 5s

Muestra el indicador “escribiendo…” en el chat del destinatario y dispara pause automáticamente tras 5 segundos (gracias a duration: 5). Ideal para preceder el envío de un mensaje 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)
}

Grabando audio

Muestra “grabando audio…” con state: "recording". Sin duration, el indicador permanece hasta que WhatsApp lo expira naturalmente (~5–10s) o hasta que envíes 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

Con state: "pause", finaliza inmediatamente cualquier indicador “escribiendo…” o “grabando…” activo en el chat. Útil cuando un flujo automático termina antes del duration planeado.

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)
}

Respuesta exitosa

Con duración
Sin duración

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
}

Parámetros de ruta

string

requerido

Nombre de la instancia.

Cabeceras

string

requerido

TokenAccount o TokenInstance.

Cuerpo de la solicitud

string

requerido

Número de teléfono o JID del chat.

string

requerido

typing / recording / pause / paused (sin distinguir mayúsculas/minúsculas).

int

predeterminado:"0"

Segundos hasta el auto-pause (0–60). Cuando es >0 y state es typing/recording, la API envía automáticamente pause tras ese intervalo. Ignorado cuando es pause/paused.

Estados aceptados

`state`	Efecto
`typing`	”escribiendo…” en el chat del destinatario
`recording`	”grabando audio…”
`pause` / `paused`	Cancela cualquier indicador actual

Notas

Las presencias son efímeras, no se persisten, y WhatsApp expira el indicador en el teléfono del destinatario en ~5–10s incluso sin un pause explícito.
duration > 60 se trunca a 60 (cap interno).
En chats donde el destinatario desactivó las confirmaciones de presencia, el indicador puede no aparecer.

Respuestas de error

HTTP	`error.message`	Cuándo
400	`Invalid request body`	JSON malformado.
400	`Number is required`	Campo faltante.
400	`State is required. Use 'typing', 'recording', or 'pause'`	`state` vacío.
400	`Invalid state. Use 'typing', 'recording', or 'pause'`	Fuera del enum.
401	`Invalid token`	,
404	`Instance not found`	,
503	`Instance is not connected to WhatsApp`	Sin sesión activa.

Introducción

Instancia

Eventos

Mensajes

Llamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidad

Enviar presencia

Ejemplos

Escribiendo por 5s

Grabando audio

Cancelar indicador

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Estados aceptados

Notas

Respuestas de error

​Ejemplos

​Escribiendo por 5s

​Grabando audio

​Cancelar indicador

​Respuesta exitosa

​Parámetros de ruta

​Cabeceras

​Cuerpo de la solicitud

​Estados aceptados

​Notas

​Respuestas de error

Ejemplos

Escribiendo por 5s

Grabando audio

Cancelar indicador

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Estados aceptados

Notas

Respuestas de error