Send presence

POST

api

chat

presence

:instance

Send presence

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 or TokenInstance • Rate-limit: Global (100/min) • Idempotent: yes (ephemeral) Emits a presence indicator (“typing…”, “recording audio…”, or pause) to a chat. Ideal to simulate realistic interaction before sending a message.

Examples

Typing for 5s

Shows the “typing…” indicator on the recipient’s chat and automatically dispatches pause after 5 seconds (thanks to duration: 5). Ideal to precede sending a text message.

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

Recording audio

Displays “recording audio…” with state: "recording". Without duration, the indicator stays until WhatsApp expires it naturally (~5–10s) or until you send pause manually.

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

Cancel indicator

With state: "pause", immediately ends any active “typing…” or “recording…” indicator on the chat. Useful when an automated flow ends before the planned duration.

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

Success response

With duration
Without duration

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

required

Instance name.

Headers

string

required

TokenAccount or TokenInstance.

Request body

string

required

Phone number or JID of the chat.

string

required

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

int

default:"0"

Seconds until auto-pause (0–60). When >0 and state is typing/recording, the API automatically sends pause after that interval. Ignored when pause/paused.

Accepted states

`state`	Effect
`typing`	”typing…” on the recipient’s chat
`recording`	”recording audio…”
`pause` / `paused`	Cancels any current indicator

Notes

Presences are ephemeral, they are not persisted, and WhatsApp expires the indicator on the recipient’s phone in ~5–10s even without an explicit pause.
duration > 60 is truncated to 60 (internal cap).
In chats where the recipient disabled presence acknowledgments, the indicator may not appear.

Error responses

HTTP	`error.message`	When
400	`Invalid request body`	Malformed JSON.
400	`Number is required`	Missing field.
400	`State is required. Use 'typing', 'recording', or 'pause'`	Empty `state`.
400	`Invalid state. Use 'typing', 'recording', or 'pause'`	Outside the enum.
401	`Invalid token`	,
404	`Instance not found`	,
503	`Instance is not connected to WhatsApp`	No active session.

Introduction

Instance

Events

Messages

Calls

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Typebot

Observability

Examples

Typing for 5s

Recording audio

Cancel indicator

Success response

Path parameters

Headers

Request body

Accepted states

Notes

Error responses

​Examples

​Typing for 5s

​Recording audio

​Cancel indicator

​Success response

​Path parameters

​Headers

​Request body

​Accepted states

​Notes

​Error responses

Examples

Typing for 5s

Recording audio

Cancel indicator

Success response

Path parameters

Headers

Request body

Accepted states

Notes

Error responses