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
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
orgIdstringRequired
Body
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
post
/v3/org/{orgId}/lead/chatroom
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": "2025-12-06T03:09:25.780Z",
  "deactivation_ts": "2025-12-06T03:09:25.780Z"
}

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
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
orgIdstringRequired
chatroomIdstringRequired
Body
Responses
200

Successfully re-assigned the chatroom

application/json
post
/v3/org/{orgId}/lead/chatroom/{chatroomId}/reassign
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": "2025-12-06T03:09:25.780Z",
  "deactivation_ts": "2025-12-06T03:09:25.780Z"
}

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
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
orgIdstringRequired
Body
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
post
/v2/org/{orgId}/chatroom
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": "2025-12-06T03:09:25.780Z",
  "deactivation_ts": "2025-12-06T03:09:25.780Z"
}

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
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
orgIdstringRequired
chatroomIdstringRequired
Body
user_idstringRequired
Responses
200

Successfully reassigned the chatroom

application/json
post
/v2/org/{orgId}/waba/chatroom/{chatroomId}/reassign
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": "2025-12-06T03:09:25.780Z",
  "deactivation_ts": "2025-12-06T03:09:25.780Z"
}

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
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
orgIdstringRequired
chatroomIdstringRequired
Body
deactivation_reasonstring · enumOptionalPossible values:
Responses
put
/v1/org/{orgId}/contacts/chatroom/{chatroomId}/deactivate
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
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
orgIdstringRequired
chatroomIdstringRequired
Query parameters
force_deactivatebooleanOptionalDefault: false
Responses
put
/v1/org/{orgId}/contacts/chatroom/{chatroomId}/activate
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
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
orgIdstringRequired
contactIdstringRequired
Responses
200

Successfully fetched chatroom by contact

application/json
get
/v1/org/{orgId}/chatroom/contact/{contactId}
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": "2025-12-06T03:09:25.780Z",
  "deactivation_ts": "2025-12-06T03:09:25.780Z",
  "waba": {
    "remote_waba_id": "text",
    "matrix_host_name": "text",
    "name": "text"
  }
}
PreviousContactNextMedia

Last updated