Chatroom

This page outlines the API documentation for creating, managing, reassigning, and activating/deactivating chatrooms in Saleschat.pro.

Create a new chatroom for a lead V3

post

• Roles Allowed: ADMIN

• Impersonated User Allowed: False

• Partner Allowed: True

• leadId is the id field in contact table

• API will create a chatroom or return an existing chatroom for this contact

• Chatroom will be created for the provided Waba and the Phone number if they are registered for this org

• Chatroom's display name will be display name if provided

• Otherwise Chatroom's display name will be contact's crm_id + FN + LN

• After a certain thresold number of days of inactivity a chatroom is Deactivated. After Deactivation of chatroom, a new chatroom for the same contact with a different crmId can be created

• After a certain thresold number of days of creation a chatroom is Expired. After Expiry of chatroom, a new chatroom for the same contact with a different crmId can be created

• At any point of time only one active chatroom (not deactivated & not expired) can exist for a unique phone number

• On every chatroom creation, a new contact-waba is created if not already present

• Each contact can only have one waba mapping

• Every contact-waba mapping is per Waba per Waba Phone, i.e any contact with same phone can one active chatroom present across multiple Waba Phone(s)

• By default (fail_if_chatroom_exists_on_other_wabaphone = true), in case of an existing contact-waba mapping, we throw a Conflict upon trying to create a chatroom for the same phone number.

• For fail_if_chatroom_exists_on_other_wabaphone = false, we create chatroom with same phone number with the next available Waba Phone.

• This API allows chatroom handover, that is, that the agent will only be assigned to chatroom after the lead has responded

• Assignment of this chatroom can be done by specifying a user or a group from which the user can be selected

Authorizations

bearer-keyx-org-api-key

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

orgIdstringRequired

Body

application/json

lead_idstringRequired

display_namestringOptionalDeprecated

remote_waba_idstringOptional

remote_phone_idstringOptional

force_deactivatebooleanOptional

When this option is set to true, then all the existing chatrooms for the lead will be deactivated and a new chatroom would be created.

Default: false

fail_if_chatroom_exists_on_other_waba_phonebooleanOptional

If set to true, the request will fail if a chatroom already exists on a different WABA phone.

Default: true

Responses

200

Successfully created the chatroom

application/json

400

Bad request

application/json

401

Unauthorized - Authentication is required

application/json

403

User or Partner does not have access to this org

application/json

404

Waba does not exist / WabaPhone does not exist / User or group does not exist

application/json

409

Active chatroom already exists

application/json

422

Required fields are missing or invalid values are provided

application/json

500

Internal Exception

application/json

post

/v3/org/{orgId}/lead/chatroom

HTTPcURLJavaScriptPython

POST /v3/org/{orgId}/lead/chatroom HTTP/1.1
Host: apis.saleschat.pro
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 245

{
  "lead_id": "text",
  "remote_waba_id": "text",
  "remote_phone_id": "text",
  "force_deactivate": false,
  "fail_if_chatroom_exists_on_other_waba_phone": true,
  "assign_details": {
    "assign_mode": "USER",
    "user_id": "text",
    "group_id": "text",
    "assign_on_handover": false
  }
}

{
  "chatroom_id": "text",
  "external_ref_id": "text",
  "is_existing": true,
  "is_deactivated": true,
  "is_expired": true,
  "expiry_ts": "2026-01-25T04:14:00.716Z",
  "deactivation_ts": "2026-01-25T04:14:00.716Z"
}

Reassign Chatroom V3

post

• Roles Allowed: ADMIN

• Impersonated User Allowed: False

• Partner Allowed: True

• This API works only for chatrooms created for waba. Hence explicitly added /waba in the API endpoint

• API will revoke access of all the existing users from the chatroom and add new users to the chatroom

• Depending on the room history visibility flag while creating the chatroom the new users may or may not see messages from the past

• This API allows chatroom handover, that is, that the agent will only be assigned to chatroom after the lead has responded

• Reassignment of this chatroom can be done by specifying a user or a group from which the user can be selected

Authorizations

bearer-keyx-org-api-key

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

orgIdstringRequired

chatroomIdstringRequired

Body

application/json

Responses

200

Successfully re-assigned the chatroom

application/json

400

Bad request

application/json

401

Unauthorized - Authentication is required

application/json

403

User or Partner does not have access to this org

application/json

404

Chatroom does not exist for this org / OrgId does not exist

application/json

422

Required fields are missing or invalid values are provided

application/json

500

Internal Exception

application/json

post

/v3/org/{orgId}/lead/chatroom/{chatroomId}/reassign

HTTPcURLJavaScriptPython

POST /v3/org/{orgId}/lead/chatroom/{chatroomId}/reassign HTTP/1.1
Host: apis.saleschat.pro
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 103

{
  "assign_details": {
    "assign_mode": "USER",
    "user_id": "text",
    "group_id": "text",
    "assign_on_handover": false
  }
}

{
  "chatroom_id": "text",
  "external_ref_id": "text",
  "is_existing": true,
  "is_deactivated": true,
  "is_expired": true,
  "expiry_ts": "2026-01-25T04:14:00.716Z",
  "deactivation_ts": "2026-01-25T04:14:00.716Z"
}

Create Chatroom V2

post

• Roles Allowed: ADMIN

• Impersonated User Allowed: False

• Partner Allowed: True

• contactId is the id field in contact table

• API will create a chatroom or return an existing chatroom for this contact

• Chatroom will be created for the provided Waba and the Phone number if they are registered for this org

• Chatroom's display name will be display name if provided

• Otherwise Chatroom's display name will be contact's crm_id + FN + LN

• After a certain thresold number of days of inactivity a chatroom is Deactivated. After Deactivation of chatroom, a new chatroom for the same contact with a different crmId can be created

• After a certain thresold number of days of creation a chatroom is Expired. After Expiry of chatroom, a new chatroom for the same contact with a different crmId can be created

• At any point of time only one active chatroom (not deactivated & not expired) can exist for a unique phone number

• On every chatroom creation, a new contact-waba is created if not already present

• Each contact can only have one waba mapping

• Every contact-waba mapping is per Waba per Waba Phone, i.e any contact with same phone can one active chatroom present across multiple Waba Phone(s)

• By default (fail_if_chatroom_exists_on_other_wabaphone = true), in case of an existing contact-waba mapping, we throw a Conflict upon trying to create a chatroom for the same phone number.

• For fail_if_chatroom_exists_on_other_wabaphone = false, we create chatroom with same phone number with the next available Waba Phone.

Authorizations

bearer-keyx-org-api-key

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

orgIdstringRequired

Body

application/json

user_idstringRequired

display_namestringOptional

remote_waba_idstringOptional

remote_phone_idstringOptional

contact_idstringRequired

fail_if_chatroom_exists_on_other_wabaphonebooleanOptional

assign_on_handoverbooleanOptional

Responses

200

Successfully returning the chatroom

application/json

401

Unauthorized - Authentication is required

application/json

403

User or Partner does not have access to this org

application/json

404

OrgId, UserId, Contact or WABA does not exist

application/json

409

Active chatroom already exists with a different crmId

application/json

422

Required fields are missing or invalid values are provided

application/json

500

Internal Exception

application/json

post

/v2/org/{orgId}/chatroom

HTTPcURLJavaScriptPython

POST /v2/org/{orgId}/chatroom HTTP/1.1
Host: apis.saleschat.pro
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 185

{
  "user_id": "text",
  "display_name": "text",
  "remote_waba_id": "text",
  "remote_phone_id": "text",
  "contact_id": "text",
  "fail_if_chatroom_exists_on_other_wabaphone": true,
  "assign_on_handover": true
}

{
  "chatroom_id": "text",
  "external_ref_id": "text",
  "is_existing": true,
  "is_deactivated": true,
  "is_expired": true,
  "expiry_ts": "2026-01-25T04:14:00.716Z",
  "deactivation_ts": "2026-01-25T04:14:00.716Z"
}

Reassign Chatroom V2

post

• Roles Allowed: ADMIN

• Impersonated User Allowed: False

• Partner Allowed: True

• This API works only for chatrooms created for waba. Hence explicitly added /waba in the API endpoint

• API will revoke access of all the existing users from the chatroom and add new users to the chatroom

• Depending on the room history visibility flag while creating the chatroom the new users may or may not see messages from the past

Authorizations

bearer-keyx-org-api-key

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

orgIdstringRequired

chatroomIdstringRequired

Body

application/json

user_idstringRequired

Responses

200

Successfully reassigned the chatroom

application/json

401

Unauthorized - Authentication is required

application/json

403

User or Partner does not have access to this org

application/json

404

Chatroom does not exist for this org

application/json

422

Required fields are missing or invalid values are provided

application/json

500

Internal Exception

application/json

post

/v2/org/{orgId}/waba/chatroom/{chatroomId}/reassign

HTTPcURLJavaScriptPython

POST /v2/org/{orgId}/waba/chatroom/{chatroomId}/reassign HTTP/1.1
Host: apis.saleschat.pro
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 18

{
  "user_id": "text"
}

{
  "chatroom_id": "text",
  "external_ref_id": "text",
  "is_existing": true,
  "is_deactivated": true,
  "is_expired": true,
  "expiry_ts": "2026-01-25T04:14:00.716Z",
  "deactivation_ts": "2026-01-25T04:14:00.716Z"
}

Deactivate Chatroom

put

• Roles Allowed: ADMIN

• Impersonated User Allowed: True

• Partner Allowed: True

• Message aren't allowed in a deactivated chatroom.

• After a certain threshold of inactivity based on org config a chatroom is marked deactivated

• A deactivated chatroom can be activated

Authorizations

bearer-key

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

orgIdstringRequired

chatroomIdstringRequired

Body

application/json

deactivation_reasonstring · enumOptionalPossible values:

Responses

202

Successfully accepted request for deactivating contact chatroom

application/json

400

Bad request

application/json

401

Unauthorized - Authentication is required

application/json

403

Forbidden - You don't have permission to access this resource

application/json

500

Failed to deactivate chatroom due to some internal error

application/json

put

/v1/org/{orgId}/contacts/chatroom/{chatroomId}/deactivate

HTTPcURLJavaScriptPython

PUT /v1/org/{orgId}/contacts/chatroom/{chatroomId}/deactivate HTTP/1.1
Host: apis.saleschat.pro
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 40

{
  "deactivation_reason": "LEAD_OPTED_OUT"
}

text

Activate Chatroom

put

• Roles Allowed: ADMIN

• Impersonated User Allowed: False

• Partner Allowed: True

• A flag force_deactivate is used with false default value

• By default we won't allow activation if any active chatroom already exists with the same phone number

• If force_deactivate is set to true, then all existing active chatrooms for the same Waba Phone with same pn will be deactivated

Authorizations

bearer-key

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

orgIdstringRequired

chatroomIdstringRequired

Query parameters

force_deactivatebooleanOptionalDefault: false

Responses

202

Successfully accepted request for re-activating contact chatroom

application/json

400

Bad request

application/json

401

Unauthorized - Authentication is required

application/json

403

Forbidden - You don't have permission to access this resource

application/json

500

Failed to activate chatroom due to some internal error

application/json

put

/v1/org/{orgId}/contacts/chatroom/{chatroomId}/activate

HTTPcURLJavaScriptPython

PUT /v1/org/{orgId}/contacts/chatroom/{chatroomId}/activate HTTP/1.1
Host: apis.saleschat.pro
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

text

Get Chatroom by Contact

get

• Roles Allowed: MEMBER

• Impersonated User Allowed: True

• Partner Allowed: True

Authorizations

bearer-key

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

orgIdstringRequired

contactIdstringRequired

Responses

200

Successfully fetched chatroom by contact

application/json

400

Bad request

application/json

401

Unauthorized - Authentication is required

application/json

403

Forbidden - You don't have permission to access this resource

application/json

404

No contact waba mapping found

application/json

422

Required fields are missing or invalid values are provided

application/json

500

Failed to fetch chatroom due to some internal error

application/json

get

/v1/org/{orgId}/chatroom/contact/{contactId}

HTTPcURLJavaScriptPython

GET /v1/org/{orgId}/chatroom/contact/{contactId} HTTP/1.1
Host: apis.saleschat.pro
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "chatroom_id": "text",
  "external_ref_id": "text",
  "is_existing": true,
  "is_deactivated": true,
  "is_expired": true,
  "expiry_ts": "2026-01-25T04:14:00.716Z",
  "deactivation_ts": "2026-01-25T04:14:00.716Z",
  "waba": {
    "remote_waba_id": "text",
    "matrix_host_name": "text",
    "name": "text"
  }
}