Conversations

3 API calls in this section.

List Conversations

Communications & Feedback / Messaging / Conversations

GET/messaging/conversations?tenant_id={{tenant_id}}&type=&status=&user_id=&page=1&limit=20

Retrieves conversations based on specified filter criteria. Supports pagination and filtering by type, status, and user ID. Authorization: - Requires valid authentication token - Users can view their own conversations - Users with 'view:tenant' or 'manage:messaging:tenant' permission can view all conversations Response: - Returns paginated list of conversations with participants and latest message - Includes unread message count for each conversation

Send a bearer token in the Authorization header for an authenticated OnDi user session.

Request

curl

1curl --request GET "$ONDI_BASE_URL/messaging/conversations?tenant_id={{tenant_id}}&type=&status=&user_id=&page=1&limit=20" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "Content-Type: application/json"

Query parameters

tenant_idOptional

query string

{{tenant_id}}

UUID of the tenant (required if not in auth token)

typeOptional

query string

Filter by conversation type (support, order, delivery, team, etc.)

statusOptional

query string

Filter by conversation status

user_idOptional

query string

UUID of the user to filter conversations by (defaults to authenticated user)

pageOptional

query string

1

Page number for pagination (default: 1)

limitOptional

query string

20

Number of items per page (default: 20)

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

Content-TypeOptional

header string

application/json

Responses

Success Response200OK

Error - Insufficient Permissions403Forbidden

Create Conversation

Communications & Feedback / Messaging / Conversations

POST/messaging/conversations?tenant_id={{tenant_id}}

Creates a new conversation. Rules: - If delivery_id is provided, only one conversation per delivery is allowed. If a conversation for that delivery exists, it will be reused and new participants will be added. - For drivers/users/dispatchers, delivery_id is required. - For free (non-delivery) conversations, only dispatcher/admin can create. - For delivery conversations, participants are auto-determined (driver + customer) and optional in request. If provided, they are added as additional participants. - For free conversations, participants are required. - The delivery's customer (user who created the delivery) is auto-added as a participant for delivery conversations. - Creator is automatically added as admin if not in participants list. - All participants must belong to the tenant. - If title is not provided and delivery_id is present, the title will be auto-generated as #<external reference id> - <customer name>. - The type field is always set to 'order' by the backend and is not required in the request.

Send a bearer token in the Authorization header for an authenticated OnDi user session.

Request

curl

1curl --request POST "$ONDI_BASE_URL/messaging/conversations?tenant_id={{tenant_id}}" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "Content-Type: application/json" \4  --header "Content-Type: application/json" \5  --data '{6  "delivery_id": "delivery-uuid",7  "metadata": {8    "order_id": "12345",9    "priority": "high"10  }11}'

Request body

json

1{2  "delivery_id": "delivery-uuid",3  "metadata": {4    "order_id": "12345",5    "priority": "high"6  }7}

Query parameters

tenant_idOptional

query string

{{tenant_id}}

UUID of the tenant (required if not in auth token)

Request body fields

delivery_idExample

string

Example field from the request body.

metadataExample

object

Example field from the request body.

metadata.order_idExample

string

Example field from the request body.

metadata.priorityExample

string

Example field from the request body.

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

Content-TypeOptional

header string

application/json

Responses

Success Response (New or Existing Delivery Conversation)201Created

Success Response (Existing Delivery Conversation)200OK

Error - Free Conversation Not Allowed403Forbidden

Error - Delivery Conversation Required403Forbidden

Get Conversation

Communications & Feedback / Messaging / Conversations

GET/messaging/conversations/:conversationId?tenant_id={{tenant_id}}

Retrieves detailed information about a specific conversation including participants and latest message. Authorization: - Requires valid authentication token - User must be a participant in the conversation OR have 'view:tenant' permission OR be system admin Path Parameters: - conversationId: UUID of the conversation to retrieve Response: - Returns conversation details with participant information and latest message - Includes participant user details (name, email, avatar)

Send a bearer token in the Authorization header for an authenticated OnDi user session.

Request

curl

1curl --request GET "$ONDI_BASE_URL/messaging/conversations/:conversationId?tenant_id={{tenant_id}}" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "Content-Type: application/json"

Path parameters

conversationIdRequired

path string

uuid

UUID of the conversation to retrieve

Query parameters

tenant_idOptional

query string

{{tenant_id}}

UUID of the tenant (required if not in auth token)

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

Content-TypeOptional

header string

application/json

Responses

Success Response200OK

Error - Conversation Not Found404Not Found

Error - Unauthorized Access403Forbidden