Typing indicator

The typing indicator shows the recipient that a message is being written.

Automatic indicator

Turbo Notify shows the typing indicator on its own for a short time before each send. Before that, the conversation is opened the way a person would: the number shows as online and the unread messages in that conversation are marked as read.

Use the endpoints below only when you need manual control over the typing indicator.

Start typing

To show that a message is being written, send a request with is_typing set to true.

cURL

typing.sh

curl -X POST \
  https://api.turbonotify.com/v1/typing-indicator \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {"number": "+5511988887777"},
    "is_typing": true
  }'

Node

typing.js

const response = await fetch('https://api.turbonotify.com/v1/typing-indicator', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: { number: '+5511988887777' },
    is_typing: true
  })
});

console.log(response.status); // 202

Python

typing.py

import requests

url = "https://api.turbonotify.com/v1/typing-indicator"
headers = {
    "Authorization": "Bearer YOUR_KEY",
    "Content-Type": "application/json"
}
data = {
    "to": {"number": "+5511988887777"},
    "is_typing": True
}

response = requests.post(url, json=data, headers=headers)
print(response.status_code)  # 202

Go

typing.go

package main

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

func main() {
    payload := strings.NewReader(`{"to": {"number": "+5511988887777"}, "is_typing": true}`)
    req, _ := http.NewRequest("POST", "https://api.turbonotify.com/v1/typing-indicator", payload)
    req.Header.Set("Authorization", "Bearer YOUR_KEY")
    req.Header.Set("Content-Type", "application/json")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    fmt.Println(resp.StatusCode) // 202
}

PHP

typing.php

<?php
$url = 'https://api.turbonotify.com/v1/typing-indicator';
$data = [
    'to' => ['number' => '+5511988887777'],
    'is_typing' => true
];

$options = [
    'http' => [
        'header' => [
            'Authorization: Bearer YOUR_KEY',
            'Content-Type: application/json'
        ],
        'method' => 'POST',
        'content' => json_encode($data)
    ]
];

$context = stream_context_create($options);
file_get_contents($url, false, $context);
var_dump($http_response_header);
?>

C#

Typing.cs

using System.Text;
using System.Text.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_KEY");

var data = new {
    to = new { number = "+5511988887777" },
    is_typing = true
};

var json = JsonSerializer.Serialize(data);
var content = new StringContent(json, Encoding.UTF8, "application/json");

var response = await client.PostAsync("https://api.turbonotify.com/v1/typing-indicator", content);
Console.WriteLine((int)response.StatusCode); // 202

Java

Typing.java

import java.net.http.*;
import java.net.URI;

public class Typing {
    public static void main(String[] args) throws Exception {
        var client = HttpClient.newHttpClient();

        var json = """
            {
                "to": {"number": "+5511988887777"},
                "is_typing": true
            }
            """;

        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.turbonotify.com/v1/typing-indicator"))
            .header("Authorization", "Bearer YOUR_KEY")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        var response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode()); // 202
    }
}

Turbo Notify responds with an asynchronous acceptance:

HTTP status: 202

{
  "operation_id": "op_typing_9f3c2a1d47e8",
  "status": {
    "state": "pending",
    "at": "2025-07-16T10:00:00Z"
  }
}

What happens when typing starts

Starting to type also opens the conversation, as in a WhatsApp used by a person, in this order:

1. The number shows as online, if it was not already.
2. The messages the number received in that conversation and has not read yet are marked as read (the “blue ticks” for whoever sent them).
3. After a short random pause, between 0.3 and 1.5 seconds, “typing…” appears.

This way, “typing…” never shows up over unread messages. The number goes back offline on its own a few minutes after the last interaction with any conversation (this is the presence shown in WhatsApp: the number’s connection and status do not change).

All of this is automatic. It does not use message or contact quota and does not produce a webhook event. The plan required for the typing indicator stays the same: the read that comes with starting to type does not depend on the read feature of the Business plan or higher, which only applies to marking as read manually.

Stop typing

To stop the typing indicator manually, send the same request with is_typing set to false. Stopping only removes the indicator: no message is marked as read.

cURL

typing.sh

curl -X POST \
  https://api.turbonotify.com/v1/typing-indicator \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {"number": "+5511988887777"},
    "is_typing": false
  }'

Node

typing.js

const response = await fetch('https://api.turbonotify.com/v1/typing-indicator', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: { number: '+5511988887777' },
    is_typing: false
  })
});

console.log(response.status); // 202

Python

typing.py

import requests

url = "https://api.turbonotify.com/v1/typing-indicator"
headers = {
    "Authorization": "Bearer YOUR_KEY",
    "Content-Type": "application/json"
}
data = {
    "to": {"number": "+5511988887777"},
    "is_typing": False
}

response = requests.post(url, json=data, headers=headers)
print(response.status_code)  # 202

Go

typing.go

package main

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

func main() {
    payload := strings.NewReader(`{"to": {"number": "+5511988887777"}, "is_typing": false}`)
    req, _ := http.NewRequest("POST", "https://api.turbonotify.com/v1/typing-indicator", payload)
    req.Header.Set("Authorization", "Bearer YOUR_KEY")
    req.Header.Set("Content-Type", "application/json")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    fmt.Println(resp.StatusCode) // 202
}

PHP

typing.php

<?php
$url = 'https://api.turbonotify.com/v1/typing-indicator';
$data = [
    'to' => ['number' => '+5511988887777'],
    'is_typing' => false
];

$options = [
    'http' => [
        'header' => [
            'Authorization: Bearer YOUR_KEY',
            'Content-Type: application/json'
        ],
        'method' => 'POST',
        'content' => json_encode($data)
    ]
];

$context = stream_context_create($options);
file_get_contents($url, false, $context);
var_dump($http_response_header);
?>

C#

Typing.cs

using System.Text;
using System.Text.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_KEY");

var data = new {
    to = new { number = "+5511988887777" },
    is_typing = false
};

var json = JsonSerializer.Serialize(data);
var content = new StringContent(json, Encoding.UTF8, "application/json");

var response = await client.PostAsync("https://api.turbonotify.com/v1/typing-indicator", content);
Console.WriteLine((int)response.StatusCode); // 202

Java

Typing.java

import java.net.http.*;
import java.net.URI;

public class Typing {
    public static void main(String[] args) throws Exception {
        var client = HttpClient.newHttpClient();

        var json = """
            {
                "to": {"number": "+5511988887777"},
                "is_typing": false
            }
            """;

        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.turbonotify.com/v1/typing-indicator"))
            .header("Authorization", "Bearer YOUR_KEY")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        var response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode()); // 202
    }
}

Turbo Notify responds with an asynchronous acceptance:

HTTP status: 202

{
  "operation_id": "op_typing_5b8e0d6c21fa",
  "status": {
    "state": "pending",
    "at": "2025-07-16T10:00:05Z"
  }
}

Available recipients

The to field accepts exactly one of the three forms below, just like the send message route:

Form	Example	When to use
number	{"number": "+5511988887777"}	A known E.164 number
group_id	{"group_id": "grp_…"}	A WhatsApp group
contact_id	{"contact_id": "ct_…"}	The contact’s ID in Turbo Notify (the phone number is looked up for you)

Typing indicator in groups

To show the typing indicator in a WhatsApp group, use to.group_id with the group’s identifier instead of to.number.

Requires the Business plan or higher

Sending a typing indicator (like a message) to a group_id requires the groups:messages feature, available from the Business plan. On the Free and Lone Wolf plans you still receive group messages, list groups (GET /v1/numbers/{ref}/groups) and get group details as usual. Only sending to a group (including the typing indicator) is blocked with 402:

HTTP status: 402

{
  "error": "feature_not_available"
}

See Quota and usage and Group limitations.

typing-group.sh

curl -X POST \
  https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS/typing-indicator \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {"group_id": "grp_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},
    "is_typing": true
  }'

The group_id is the group’s identifier in the grp_{hex32} format, returned by the list groups endpoint.

Typing indicator by contact_id

Use to.contact_id to show typing to a contact in your Turbo Notify contacts without giving the phone number directly. The phone number is taken from the contact’s record.

typing-contact.sh

curl -X POST \
  https://api.turbonotify.com/v1/numbers/NUMBER_ALIAS/typing-indicator \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {"contact_id": "ct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},
    "is_typing": true
  }'

Typing indicator from an extra number

In the nested form, the sender of the typing indicator is always the number in the path. To type from a registered, active extra number, use that form with the number’s alias in place of {ref}:

typing.sh

curl -X POST \
  https://api.turbonotify.com/v1/numbers/vendas-sp/typing-indicator \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {"number": "+5511988887777"},
    "is_typing": true
  }'

The two forms handle the sender differently:

• Nested (POST /v1/numbers/{ref}/typing-indicator): the sender is always the number in the path. A from field in the body is ignored.
• Flat (POST /v1/typing-indicator): always sends from the main number (main). A from field in the body does not cause a validation error, but it is silently dropped: the request returns 202 Accepted and the typing indicator comes from the main number, not from the number given in from.

To send a typing indicator from an extra number, you must use the nested form, with the extra number’s alias in the URL path. The flat form has no way to choose the sender, and because it reports no error, a from in the body gives the false impression that it worked.

If the alias in the path is not registered, or the number is not active, the request is rejected.

Learn more about extra numbers.

Webhook events

The typing indicator has no completion confirmation: the 202 Accepted only confirms the asynchronous acceptance, and no webhook event is delivered for these requests.

Possible errors

Status	Error code	Description
400	contact_not_found	The contact_id given in to does not belong to this organization.
400	contacts_not_enabled	Sending by contact_id is unavailable right now. Try again later; if it persists, contact support.
400	groups_not_enabled	Group features are unavailable right now. Try again later; if it persists, contact support.
400	invalid_recipient	The recipient given in to could not be resolved to a sendable address. Giving none, or more than one, of number, group_id and contact_id returns 422 validation_error.
402	feature_not_available	The feature is not available on your plan.
401	not_authenticated	The API key is invalid or missing.
403	insufficient_scope	The API key does not have the messages:send scope (the response includes required_scope).
404	number_not_found	The {ref} in the path does not match any number on the account (on the flat route: the account has no main number yet).
400	invalid_number_id	The value in the URL starts with num_ but is not a valid number id.
404	group_not_found	The group_id given in to was not found.
409	number_not_connected	The number is not connected to WhatsApp. Reconnect the number and try again.
422	sender_not_found	The alias or number given does not match any sender on the account.
422	validation_error	The request body is malformed or failed validation. The response includes details.errors with the list of invalid fields.
500	internal_error	Unexpected internal server error.