Skip to content
Whats91

Take ownership of one conversation so Whats91 internal automation stays quiet.

Acquire Session

Summary

Take ownership of one conversation so Whats91 internal automation stays quiet.

Prerequisites

  • Authorization: Bearer w91_live_xxx
  • Content-Type: application/json for JSON requests

Related documentation

Custom BoardsList Keyword ExclusionsCreate Keyword ExclusionUpdate Keyword Exclusion

A custom-board session is a lease over one conversation, keyed by customer, phoneNumberId, and contactPhone. While the lease is active Whats91 internal automation is suppressed for that contact on that sender, and your board is responsible for replying.

Note

Sessions are temporary in-memory leases. Whats91 does not write a session table for acquire, renew, active lookup, or release. Only keyword exclusions are stored durably.

SettingValue
Default TTL1800 seconds (30 minutes)
Minimum TTL30 seconds
Maximum TTL86400 seconds (24 hours)
Owner tokenReturned by first acquire and by same-idempotency replay. Stored by Whats91 only as a hash.
POST/api/v3/custom-boards/sessions/acquire

Acquire a conversation session lease.

ParameterTypeRequiredDescription
senderIdstringOptionalRequired unless phoneNumberId or a number-scoped token resolves the sender.
phoneNumberIdstringOptionalRequired unless senderId or a number-scoped token resolves the sender.
contactPhonestringRequiredCustomer mobile number whose conversation is being acquired. Digits are normalized.
boardUidstringRequiredStable external board identifier.
keywordstringOptionalKeyword that triggered takeover. Stored for audit and debugging.
ttlSecondsintegerOptionalLease duration. Default 1800, maximum 86400.
cURL
curl -X POST "https://graph.whats91.com/api/v3/custom-boards/sessions/acquire" \
  -H "Authorization: Bearer w91_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: board-msg-20260628-001" \
  -d '{
    "senderId": "913614068784",
    "phoneNumberId": "486728586446799",
    "contactPhone": "919999999999",
    "boardUid": "external-board-1",
    "keyword": "trackrod",
    "ttlSeconds": 1800
  }'
200 OK
{
  "success": true,
  "message": "Custom board session acquired",
  "data": {
    "senderId": "913614068784",
    "phoneNumberId": "486728586446799",
    "session": {
      "sessionUid": "cbs_abc123",
      "status": "ACTIVE",
      "senderId": "913614068784",
      "senderPhoneNumber": "913614068784",
      "phoneNumberId": "486728586446799",
      "contactPhone": "919999999999",
      "boardUid": "external-board-1",
      "keyword": "trackrod",
      "leaseExpiresAt": "2026-06-28T12:30:00.000Z",
      "acquiredAt": "2026-06-28T12:00:00.000Z",
      "renewedAt": null,
      "releasedAt": null,
      "ownerToken": "one-time-release-token"
    }
  },
  "metadata": {
    "apiVersion": "v3",
    "requestId": "request-uuid"
  }
}
409 Conflict
{
  "success": false,
  "message": "Session is already acquired by another custom board",
  "error_code": "SESSION_ALREADY_ACQUIRED",
  "details": {},
  "metadata": {
    "apiVersion": "v3",
    "requestId": "request-uuid"
  }
}

Important

Store session.sessionUid and session.ownerToken securely. Renew and release both require the owner token, and Whats91 can only return a usable token again when the same active lease is re-acquired with the same non-empty Idempotency-Key.

Idempotent Acquire

SituationResult
Same board, same active session, same non-empty idempotency keyReturns the active session and a usable owner token.
Different board while an active session exists409 SESSION_ALREADY_ACQUIRED.
Same board without the matching idempotency key while an active session exists409 SESSION_ALREADY_ACQUIRED.
Previous session has expiredAcquire succeeds and issues a new lease.

SDK Examples

Use these examples as starting points for server-side implementations.

cURL
curl -X POST "https://graph.whats91.com/api/v3/custom-boards/sessions/acquire" \
  -H "Authorization: Bearer w91_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "senderId": "913614068784",
  "phoneNumberId": "486728586446799",
  "contactPhone": "919999999999",
  "boardUid": "external-board-1",
  "keyword": "trackrod",
  "ttlSeconds": 1800
}'
Node.js
const response = await fetch("https://graph.whats91.com/api/v3/custom-boards/sessions/acquire", {
  method: "POST",
  headers: {
    "Authorization": "Bearer w91_live_xxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "senderId": "913614068784",
    "phoneNumberId": "486728586446799",
    "contactPhone": "919999999999",
    "boardUid": "external-board-1",
    "keyword": "trackrod",
    "ttlSeconds": 1800
  })
});

const data = await response.json();
console.log(data);
PHP
$ch = curl_init("https://graph.whats91.com/api/v3/custom-boards/sessions/acquire");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer w91_live_xxx",
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "senderId" => "913614068784",
    "phoneNumberId" => "486728586446799",
    "contactPhone" => "919999999999",
    "boardUid" => "external-board-1",
    "keyword" => "trackrod",
    "ttlSeconds" => 1800
  ])
]);

$response = curl_exec($ch);
curl_close($ch);
echo $response;
Python
import requests

response = requests.request(
    "POST",
    "https://graph.whats91.com/api/v3/custom-boards/sessions/acquire",
    headers={
        "Authorization": "Bearer w91_live_xxx",
        "Content-Type": "application/json",
    },
    json={
        "senderId": "913614068784",
        "phoneNumberId": "486728586446799",
        "contactPhone": "919999999999",
        "boardUid": "external-board-1",
        "keyword": "trackrod",
        "ttlSeconds": 1800
    }
)

print(response.json())
C#
using System.Text;

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

var request = new HttpRequestMessage(HttpMethod.Post, "https://graph.whats91.com/api/v3/custom-boards/sessions/acquire");
request.Content = new StringContent(
  """
  {
    "senderId": "913614068784",
    "phoneNumberId": "486728586446799",
    "contactPhone": "919999999999",
    "boardUid": "external-board-1",
    "keyword": "trackrod",
    "ttlSeconds": 1800
  }
  """,
  Encoding.UTF8,
  "application/json"
);

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

Related APIs

Custom Boards

Let an external board take over a WhatsApp conversation without duplicate Whats91 automation replies.

List Keyword Exclusions

List sender-scoped keyword exclusions with status filtering.

Create Keyword Exclusion

Create a sender-scoped keyword exclusion that suppresses Whats91 internal automation.

Update Keyword Exclusion

Change the board, keyword, match mode, priority, or status of an existing exclusion.