Pass, release or take a conversation - Kapso Documentation

POST

/

{phone_number_id}

/

thread_control

curl --request POST \
  --url https://api.kapso.ai/meta/whatsapp/v24.0/{phone_number_id}/thread_control \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "action": "pass",
  "control_pass": {
    "target_role": "escalation"
  },
  "metadata": "Customer asked for a human"
}
'

{
  "messaging_product": "whatsapp",
  "request_id": "<string>"
}

{
  "error": {
    "code": 2494191,
    "message": "You are not permitted to take thread control for this phone number."
  }
}

{
  "error": "thread_control_in_progress",
  "detail": "Another control action for this conversation is still in progress."
}

{
  "error": "Meta API request failed",
  "detail": "The thread control result is unknown. Do not retry automatically."
}

Authorizations

X-API-Key

string

header

required

Project API key for authentication. This is the recommended authentication method.

Get your API key from the Kapso dashboard under Integrations > API keys.

Path Parameters

phone_number_id

string

required

WhatsApp Business Phone Number ID

Body

application/json

Option 1
Option 2

messaging_product

enum<string>

required

Available options:

whatsapp

action

enum<string>

required

Available options:

take,

release,

pass

to

string

required

Customer phone number. Use to or recipient.

Example:

"15551234567"

recipient

string

Customer business-scoped user ID. Use to or recipient.

Example:

"US.13491208655302741918"

control_pass

object

Pass only. Without it, the conversation goes to the escalation app.

Show child attributes

metadata

string

Passed to the app that receives the conversation.

Maximum string length: 2000

Response

Meta accepted the action

messaging_product

string

Example:

"whatsapp"

request_id

string

Present when Meta returns it

curl --request POST \
  --url https://api.kapso.ai/meta/whatsapp/v24.0/{phone_number_id}/thread_control \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "action": "pass",
  "control_pass": {
    "target_role": "escalation"
  },
  "metadata": "Customer asked for a human"
}
'

{
  "messaging_product": "whatsapp",
  "request_id": "<string>"
}

{
  "error": {
    "code": 2494191,
    "message": "You are not permitted to take thread control for this phone number."
  }
}

{
  "error": "thread_control_in_progress",
  "detail": "Another control action for this conversation is still in progress."
}

{
  "error": "Meta API request failed",
  "detail": "The thread control result is unknown. Do not retry automatically."
}