Cases API
Cases¶
A case is a container for activities (ChatSessions).
The case resource has the following attributes.
| Attribute | Type | Editable | Description |
|---|---|---|---|
id |
UUID | read-only | The unique identifier |
organization_id |
UUID | read-only | ID of the organization who owns this case |
case_number |
string | read-only | Identifier for the case, generated automatically. Unique within the organization. |
contact_id |
UUID | optional | ID of the contact assigned to this case, or null |
contact |
object | read-only | The contact assigned to this case, with attributes id, name, email and phone. null if there is no contact. |
owner_id |
UUID | optional | ID of the user who owns this case, or null |
owner |
object | read-only | The User who owns this case, or null |
subject |
string | optional | A short, human-readable title summarizing the case. Maximum length is 512 characters. |
description |
string | optional | A detailed description or summary of the case's context or issue |
status |
string | optional | Status of this case. Can be new, in_progress or closed. Defaults to new. |
priority |
integer | optional | Priority of this case. Can be 1: "None", 2: "Low", 3: "Normal", 4: "High", 5: "Critical". Defaults to 3. |
priority_label |
string | read-only | Label of the priority of this case. Uses the organization's own priority labels if they are configured. |
latest_messaging_channel |
string | read-only | Latest messaging channel used in this case. Can be email, whatsapp, webchat or telephony |
channel_priority |
integer | read-only | Used for routing. Each channel has its predefined priority. Higher number = more urgent: telephony (4) > webchat (3) > whatsapp (2) > email (1). |
case_funnel_stage_id |
UUID | read-only | ID of the case funnel stage the case is currently in, or null |
case_funnel_stage |
object | read-only | The case funnel stage the case is currently in, with attributes id, name, visitor_visible_name, order, color and case_funnel_name. null if the case is not in a funnel. |
is_closed |
boolean | read-only | Whether the case has been closed or not. Set automatically from status. |
closed_at |
datetime | read-only | The timestamp indicating when the case was closed. Returns null if the case is still open |
is_waiting |
boolean | read-only | Indicates if the case is currently awaiting action or a response |
unread_message_count |
integer | read-only | Number of messages in this case not yet read by an agent |
latest_visitor_message_at |
datetime | read-only | When the visitor last sent a message in any of the case's activities. Equals created_at until the visitor sends a message. |
calendar_id |
UUID | read-only | ID of the calendar of the latest calendar booking (scheduled task) linked to this case, or null if there is none |
calendar_name |
string | read-only | Name of the calendar of the latest calendar booking at the time of the booking, or an empty string if there is none |
due_time |
datetime | optional | When the case is due, or null. Set automatically to the scheduled time of the latest calendar booking linked to the case, and cleared when that booking is cancelled. |
routed_user_ids |
array of UUIDs | read-only | IDs of the users the case is routed to, based on the routing of the case funnel stage the case is in |
divisions |
array of strings | optional | Business divisions of this case. Can contain Sales, Marketing and Loyalty. |
created_at |
datetime | read-only | When the case was created |
updated_at |
datetime | read-only | When the case was updated |
created_by_user_id |
UUID | read-only | ID of the user who created this case, or null if the case was created automatically |
created_by_user |
object | read-only | The User who created this case, or null |
updated_by_user_id |
UUID | read-only | ID of the user who last updated this case, or null |
updated_by_user |
object | read-only | The User who last updated this case, or null |
List external visitors cases¶
You can find out all cases that external visitor has within your organization. To learn more about external visitor identities, see External visitors.
GET /api/v5/orgs/<organization_id>/external-visitors/<external_id_jwt_token>/cases
This API endpoint returns a paginated collection of visitor cases. These are cases that belong to all contacts assigned to the same visitor.
Note: that the external_id_jwt_token is not a visitor ID but a JWT token that contains the external visitor's identity. The token must be signed with the organization's API signing key.
This endpoint takes the following GET-parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
ordering |
ordering | created_at |
Ordering of results with options created_at, -created_at or updated_at, -updated_at |
This endpoint returns:
- 200 if the request was successful
- 400 if there is a problem with the JWT token
- 401 if you are not authenticated
- 403 if you do not have active subscription
- 403 if you do not have access to the organization
- 404 if the visitor does not exist
Retrieve a single case¶
You can retrieve a single case of the external visitor:
GET /api/v5/orgs/<organization_id>/external-visitors/<external_id_jwt_token>/cases/<case_id>
This endpoint returns:
- 200 if the request was successful
- 400 if there is a problem with the JWT token
- 401 if you are not authenticated
- 403 if you do not have active subscription
- 403 if you do not have access to the organization
- 404 if the visitor or the case does not exist