Whispers - API Reference | Twitch Developers

Send Whisper

NOTE: The user sending the whisper must have a verified phone number (see the Phone Number setting in your Security and Privacy settings).

NOTE: The API may silently drop whispers that it suspects of violating Twitch policies. (The API does not indicate that it dropped the whisper; it returns a 204 status code as if it succeeded.)

Rate Limits: You may whisper to a maximum of 40 unique recipients per day. Within the per day limit, you may whisper a maximum of 3 whispers per second and a maximum of 100 whispers per minute.

Endpoint

POSThttps://api.twitch.tv/helix/whispers

Authorization

Requires one of the following:

A user access token that includes the user:manage:whispers scope.

Query Parameters

from_user_idStringRequired
The ID of the user sending the whisper. This user must have a verified phone number. This ID must match the user ID in the user access token.
to_user_idStringRequired
The ID of the user to receive the whisper.

Request Body

messageStringRequired
The whisper message to send. The message must not be empty. The maximum message lengths are:
- 500 characters if the user you're sending the message to hasn't whispered you before.
- 10,000 characters if the user you're sending the message to has whispered you before.
Messages that exceed the maximum length are truncated.

Response Codes

204No Content: Successfully sent the whisper message or the message was silently dropped.
400Bad Request: The ID in the from_user_id and to_user_id query parameters must be different.
The 'message' field must not contain an empty string.
The message contains words that Twitch's moderation settings block.
The ID in the from_user_id query parameter is not valid.
The ID in the to_user_id query parameter is not valid.
401Unauthorized: The user in the from_user_id query parameter must have a verified phone number.
The Authorization header is required and must contain a user access token.
The user access token must include the user:manage:whispers scope.
The access token is not valid.
This ID in from_user_id must match the user ID in the user access token.
The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403Forbidden: The user that you're sending the whisper to doesn't accept whispers from the sender. For example, the user turned off whispers, blocked the sender, or blocks whispers from strangers (see the Block Whispers from Strangers setting in your Security and Privacy settings).
Suspended users may not send whisper messages.
The account that's sending the message doesn't allow sending whispers.
The sender is restricted from sending whispers.
404Not Found: The ID in to_user_id was not found.
Whisper messages may not be sent to suspended users.
The ID in from_user_id was not found.
429Too Many Requests: The sending user exceeded the number of whisper requests that they may make. See Rate Limits for this endpoint above.

Request Example

curl -X POST 'https://api.twitch.tv/helix/whispers?from_user_id=123&to_user_id=456' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID' \
  -H 'Content-Type: application/json' \
  -d '{"message":"hello"}'

$headers = @{
    "Authorization" = "Bearer YOUR_ACCESS_TOKEN"
    "Client-Id"     = "YOUR_CLIENT_ID"
}

$body = '{"message":"hello"}'

$response = Invoke-RestMethod -Uri "https://api.twitch.tv/helix/whispers?from_user_id=123&to_user_id=456" `
    -Method Post -Headers $headers `
    -ContentType "application/json" -Body $body

const response = await fetch("https://api.twitch.tv/helix/whispers?from_user_id=123&to_user_id=456", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Client-Id": "YOUR_CLIENT_ID",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "message": "hello"
  }),
});

const data = await response.json();

import requests

response = requests.post(
    "https://api.twitch.tv/helix/whispers",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Client-Id": "YOUR_CLIENT_ID",
    },
    params={
        "from_user_id": "123",
        "to_user_id": "456",
    },
    json={
        "message": "hello",
    },
)

data = response.json()

body := strings.NewReader(`{"message":"hello"}`)

req, _ := http.NewRequest("POST", "https://api.twitch.tv/helix/whispers?from_user_id=123&to_user_id=456", body)
req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Set("Client-Id", "YOUR_CLIENT_ID")
req.Header.Set("Content-Type", "application/json")

res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer res.Body.Close()

data, _ := io.ReadAll(res.Body)

$ch = curl_init("https://api.twitch.tv/helix/whispers?from_user_id=123&to_user_id=456");

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Client-Id: YOUR_CLIENT_ID",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"message":"hello"}');

$response = curl_exec($ch);
curl_close($ch);

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.twitch.tv/helix/whispers?from_user_id=123&to_user_id=456");
request.Headers.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
request.Headers.Add("Client-Id", "YOUR_CLIENT_ID");

request.Content = new StringContent("{\"message\":\"hello\"}",
    Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
var data = await response.Content.ReadAsStringAsync();

let client = reqwest::Client::new();

let response = client
    .post("https://api.twitch.tv/helix/whispers?from_user_id=123&to_user_id=456")
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Client-Id", "YOUR_CLIENT_ID")
    .json(&serde_json::json!({
        "message": "hello"
    }))
    .send()
    .await?;

let data = response.text().await?;