Add additional participants to an active session. Use this endpoint for agent handoffs or multi-agent collaboration.
URI: /api/v1/agentic/conversations/{conversationId}/sessions/{sessionId}/participants
Format: application/json
HTTP Method: POST
Authentication: Bearer JWT
Path Parameters
| Parameter | Required | Description |
|---|---|---|
| conversationId | Yes | Conversation identifier. |
| sessionId | Yes | Session identifier. |
Request Headers
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer JWT token. |
| agent_id | Yes | Registered agent API name. |
Request Body Schema
| Field | Type | Required | Description |
|---|---|---|---|
| participants | Array | Yes | Participants to add. Minimum 1 required. |
| participants[].id | String | Yes | Participant identifier. Use the agent's registered API name, Individual ID, or User ID depending on participant type. |
| participants[].type | String | Yes | Participant type. Values: individual, employee, agent, or free-form string. |
| participants[].role | String | Yes | Participant role in the session. Values: owner, participant. |
Example Request
{
"participants": [
{
"id": "agent-bot-1",
"type": "agent",
"role": "participant"
}
]
}
Response Body Schema
| Field | Type | Description |
|---|---|---|
| statusCode | String | Operation status. Value: participantsAdded. |
| conversationId | String | Parent conversation identifier. |
| sessionId | String | Parent session identifier. |
Example Response
Status: 202 Accepted
{
"statusCode": "participantsAdded",
"conversationId": "...",
"sessionId": "..."
}
Error Codes
| Status Code | Description |
|---|---|
| 400 | Bad Request. Invalid request format or missing required fields. |
| 401 | Unauthorized. Invalid or missing JWT token. |
| 404 | Not Found. Conversation or session does not exist. |
| 500 | Internal Server Error. |