Skip to main content

Participants

2 API calls in this section.

Endpoints for managing participants in conversations.

Manage Participants​

Communications & Feedback / Messaging / Participants
PUT/messaging/conversations/:conversationId/participants

Manages participants in a conversation by adding, removing, or updating their roles. Supports bulk operations for multiple users.

Authorization

  • Requires valid authentication token

  • User must be conversation admin OR have 'manage:tenant' permission OR be system admin

  • Support-ticket conversations additionally require the actor to be the ticket customer, a configured tenant support user while support is enabled, or a system admin

  • A driver participant cannot manage a support-ticket conversation; unauthorized access returns HTTP 403 Insufficient Permissions

  • Conversation must be in 'active' status

Special Behaviors

  • Add: If user was previously removed, they will be reactivated

  • Remove: Soft delete (sets left_at timestamp)

  • Update: Changes participant role

  • All target users must exist in the system

Path parameters

ParameterTypeDescription
conversationIdRequiredstring

UUID of the conversation

Example: uuid

Query parameters

ParameterTypeDescription
tenant_idstring

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

Example: {{tenant_id}}

Headers

ParameterTypeDescription
Authorizationstring

Example: Bearer {{access_token}}

Content-Typestring

Example: application/json

Body parameters

ParameterTypeDescription
actionstring—
user_idsarray<string>—
rolestring—
Staging
Request
curl
1curl --globoff --request PUT "https://staging-api.ondi.io/functions/v1/messaging/conversations/${CONVERSATIONID}/participants?tenant_id=${TENANT_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "action": "add",6  "user_ids": [7    "uuid1",8    "uuid2",9    "uuid3"10  ],11  "role": "member"12}'
Other request examples (1)
Request example 1
text
1{2  "action": "add" | "remove" | "update", // required - the action to perform3  "user_ids": ["string"], // required - array of user IDs to add/remove/update4  "role": "string" // required for add and update actions (admin, member, etc.)5}

Response examples

200OK
Response body
json
1{2  "success": true,3  "message": "Operation completed successfully",4  "total_processed": 3,5  "successful": 2,6  "failed": 1,7  "results": [8    {9      "user_id": "uuid1",10      "success": true,11      "message": "Participant added successfully",12      "participant": {13        "id": "uuid",14        "conversation_id": "uuid",15        "tenant_id": "uuid",16        "user_id": "uuid1",17        "role": "member",18        "joined_at": "2023-01-01T00:00:00Z",19        "left_at": null,20        "muted": false,21        "notification_preferences": {22          "email": true,23          "push": true24        },25        "user": {26          "id": "uuid1",27          "display_name": "John Doe",28          "email": "[email protected]",29          "avatar_url": "https://example.com/avatar.jpg"30        }31      }32    },33    {34      "user_id": "uuid2",35      "success": true,36      "message": "Participant added successfully",37      "participant": {38        "id": "uuid2",39        "conversation_id": "uuid",40        "tenant_id": "uuid",41        "user_id": "uuid2",42        "role": "member",43        "joined_at": "2023-01-01T00:00:00Z",44        "left_at": null,45        "muted": false,46        "notification_preferences": {47          "email": true,48          "push": true49        },50        "user": {51          "id": "uuid2",52          "display_name": "Jane Smith",53          "email": "[email protected]",54          "avatar_url": "https://example.com/avatar2.jpg"55        }56      }57    }58  ],59  "errors": [60    {61      "user_id": "uuid3",62      "error": "participant_already_exists"63    }64  ]65}

Update Read Status​

Communications & Feedback / Messaging / Participants
GET/messaging/conversations/:conversationId/read-status

Updates the last read message for the current user in a conversation. This endpoint helps track which messages have been read by each participant.

Authorization

  • Requires valid authentication token

  • Standard conversations: user must be an active participant

  • Support-ticket conversations: only the ticket customer, a configured tenant support user while support is enabled, or a system admin can update read status

  • Active participant membership alone does not grant driver access; unauthorized support-ticket access returns HTTP 403 Insufficient Permissions

    • If provided, the message must exist in the specified conversation

    • If not provided, automatically uses the latest message in the conversation

Behavior

  • Updates the participant's last_read_message_id field

  • If no message_id is provided, finds and uses the most recent message

  • Validates that the provided message exists in the conversation

  • Only authorized participants who haven't left the conversation can update their read status

Path parameters

ParameterTypeDescription
conversationIdRequiredstring

UUID of the conversation

Example: uuid

Query parameters

ParameterTypeDescription
message_idOptionalstring

UUID of the specific message to mark as read (optional). If not provided, marks the latest message as read.

Headers

ParameterTypeDescription
Authorizationstring

Example: Bearer {{access_token}}

Content-Typestring

Example: application/json

Staging
Request
curl
1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/messaging/conversations/${CONVERSATIONID}/read-status?message_id=" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json"

Response examples

200OK
Response body
json
1{2  "success": true,3  "message": "Read status updated successfully",4  "data": {5    "participant_id": "456e7890-e89b-12d3-a456-426614174002",6    "last_read_message_id": "123e4567-e89b-12d3-a456-426614174001",7    "conversation_id": "789e0123-e89b-12d3-a456-426614174003"8  }9}