# Conversations

## Get conversations

> Fetches a conversations by agent API key. The response includes the conversation details.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"GetConversationWithFeedbacksResponseDTO":{"type":"object","properties":{"currentPage":{"type":"number","description":"Current page"},"pageSize":{"type":"number","description":"Page size"},"totalItems":{"type":"number","description":"Total items"},"totalPages":{"type":"number","description":"Total pages"},"hasNextPage":{"type":"boolean","description":"Has next page"},"hasPreviousPage":{"type":"boolean","description":"Has previous page"},"data":{"description":"List of conversations","type":"array","items":{"$ref":"#/components/schemas/ConversationWithFeedbacksResponseDTO"}}},"required":["currentPage","pageSize","totalItems","totalPages","hasNextPage","hasPreviousPage","data"]},"ConversationWithFeedbacksResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"New conversation ID"},"conversationUserId":{"type":"string","description":"Conversation user ID"},"title":{"type":"string","description":"Conversation title"},"score":{"type":"number","description":"Conversation score"},"summary":{"type":"string","description":"Conversation summary"},"aiConversationId":{"type":"string","description":"AI conversation ID"},"metadata":{"type":"object","description":"Conversation metadata"},"aiCallId":{"type":"string","description":"AI call ID"},"mode":{"type":"string","description":"Conversation mode","enum":["manual","ai"]},"conversationStateId":{"type":"string","description":"Conversation state ID"},"user":{"description":"Conversation user","allOf":[{"$ref":"#/components/schemas/ExternalApiUserResponseDTO"}]},"createdAt":{"type":"string","description":"Date the conversation was created","format":"date-time"},"updatedAt":{"type":"string","description":"Date the conversation was updated","format":"date-time"},"assignedUser":{"description":"User the conversation is assigned to","nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/AssignedUserResponseDTO"}]},"feedbacks":{"description":"Conversation feedbacks","type":"array","items":{"$ref":"#/components/schemas/FeedbackResponseDTO"}}},"required":["id","conversationUserId","aiConversationId","user","createdAt","updatedAt"]},"ExternalApiUserResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"firstName":{"type":"string","description":"User first name"},"lastName":{"type":"string","description":"User last name"},"context":{"type":"string","description":"User context"},"source":{"type":"string","description":"User source"},"fkId":{"type":"string","description":"User fkId"},"fkUserId":{"type":"string","description":"User fkUserId"},"email":{"type":"string","description":"User email"},"phoneNumber":{"type":"string","description":"User phone number"},"metadata":{"type":"object","description":"Conversation user metadata"}},"required":["id","firstName","lastName"]},"AssignedUserResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Assigned user ID"},"firstName":{"type":"string","description":"Assigned user first name"},"lastName":{"type":"string","description":"Assigned user last name"},"avatarUrl":{"type":"string","description":"Assigned user avatar URL","nullable":true},"email":{"type":"string","description":"Assigned user email"},"phoneNumber":{"type":"string","description":"Assigned user phone number","nullable":true}},"required":["id","firstName","lastName","email"]},"FeedbackResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Feedback ID"},"voteType":{"type":"string","description":"Feedback vote type","enum":["up","down"]},"question":{"type":"string","description":"Feedback question","nullable":true},"answer":{"type":"string","description":"Feedback answer","nullable":true},"comment":{"type":"string","description":"Feedback comment","nullable":true},"userEmail":{"type":"string","description":"Email of the user who provided the feedback","nullable":true},"createdAt":{"type":"string","description":"Feedback created at"},"updatedAt":{"type":"string","description":"Feedback updated at"}},"required":["id","voteType","question","answer","comment","createdAt","updatedAt"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/conversations":{"get":{"description":"Fetches a conversations by agent API key. The response includes the conversation details.","operationId":"ExternalApiConversationsController_getConversations","parameters":[{"name":"page","required":false,"in":"query","description":"Page number","schema":{"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Page size","schema":{"type":"number"}},{"name":"orderBy","required":false,"in":"query","description":"Order by","schema":{"type":"string","enum":["createdAt","updatedAt"]}},{"name":"orderDirection","required":false,"in":"query","description":"Order direction","schema":{"type":"string","enum":["ASC","DESC"]}},{"name":"searchKeyword","required":false,"in":"query","description":"Search keyword in conversation title, summary, agent name, user first and last name, email and phone number","schema":{"type":"string"}},{"name":"userId","required":false,"in":"query","description":"Conversation user ID","schema":{"format":"uuid","type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Start date of conversation updatedAt.","schema":{"format":"date-time","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date of conversation updatedAt.","schema":{"format":"date-time","type":"string"}},{"name":"withFeedbacksOnly","required":false,"in":"query","description":"If true, returns conversations with at least one feedback","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successfully received conversations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetConversationWithFeedbacksResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Get conversations","tags":["Conversations","Agent API Key"]}}}}
```

## Create a new conversation

> Creates a new conversation . The response includes the conversation ID.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"CreateConversationBodyDTO":{"type":"object","properties":{"conversationUserId":{"type":"string","description":"Conversation user ID"},"title":{"type":"string","description":"Conversation title","maxLength":255},"context":{"type":"string","description":"Conversation context","maxLength":256000},"customData":{"type":"object","description":"Conversation custom data"},"conversationStateId":{"type":"string","description":"Conversation state ID"}},"required":["conversationUserId"]},"ConversationResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"New conversation ID"},"conversationUserId":{"type":"string","description":"Conversation user ID"},"title":{"type":"string","description":"Conversation title"},"score":{"type":"number","description":"Conversation score"},"summary":{"type":"string","description":"Conversation summary"},"aiConversationId":{"type":"string","description":"AI conversation ID"},"metadata":{"type":"object","description":"Conversation metadata"},"aiCallId":{"type":"string","description":"AI call ID"},"mode":{"type":"string","description":"Conversation mode","enum":["manual","ai"]},"conversationStateId":{"type":"string","description":"Conversation state ID"},"user":{"description":"Conversation user","allOf":[{"$ref":"#/components/schemas/ExternalApiUserResponseDTO"}]},"createdAt":{"type":"string","description":"Date the conversation was created","format":"date-time"},"updatedAt":{"type":"string","description":"Date the conversation was updated","format":"date-time"},"assignedUser":{"description":"User the conversation is assigned to","nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/AssignedUserResponseDTO"}]}},"required":["id","conversationUserId","aiConversationId","user","createdAt","updatedAt"]},"ExternalApiUserResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"firstName":{"type":"string","description":"User first name"},"lastName":{"type":"string","description":"User last name"},"context":{"type":"string","description":"User context"},"source":{"type":"string","description":"User source"},"fkId":{"type":"string","description":"User fkId"},"fkUserId":{"type":"string","description":"User fkUserId"},"email":{"type":"string","description":"User email"},"phoneNumber":{"type":"string","description":"User phone number"},"metadata":{"type":"object","description":"Conversation user metadata"}},"required":["id","firstName","lastName"]},"AssignedUserResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Assigned user ID"},"firstName":{"type":"string","description":"Assigned user first name"},"lastName":{"type":"string","description":"Assigned user last name"},"avatarUrl":{"type":"string","description":"Assigned user avatar URL","nullable":true},"email":{"type":"string","description":"Assigned user email"},"phoneNumber":{"type":"string","description":"Assigned user phone number","nullable":true}},"required":["id","firstName","lastName","email"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/conversations":{"post":{"description":"Creates a new conversation . The response includes the conversation ID.","operationId":"ExternalApiConversationsController_createConversation","parameters":[],"requestBody":{"required":true,"description":"Details of the conversation to be created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateConversationBodyDTO"}}}},"responses":{"201":{"description":"Successfully created a new conversation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Create a new conversation","tags":["Conversations","Agent API Key"]}}}}
```

## Delete all user conversations in current agent

> Delete all conversations associated with specified user in current agent.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"DeleteUserConversationsBodyDTO":{"type":"object","properties":{"conversationUserId":{"type":"string","description":"Conversation user ID"}},"required":["conversationUserId"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/conversations":{"delete":{"description":"Delete all conversations associated with specified user in current agent.","operationId":"ExternalApiConversationsController_deleteAllUsersConversations","parameters":[],"requestBody":{"required":true,"description":"Provide user id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteUserConversationsBodyDTO"}}}},"responses":{"204":{"description":"Successfully delete all user conversations in current agent."},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Delete all user conversations in current agent","tags":["Conversations","Agent API Key"]}}}}
```

## Get conversation states

> Fetches all available conversation states by agent API key.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"ExternalApiGetConversationStateResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Conversation state ID","format":"uuid"},"name":{"type":"string","description":"Conversation state name"},"description":{"type":"string","description":"Conversation state description","nullable":true},"color":{"type":"string","description":"Conversation state color hex","nullable":true},"isPersistent":{"type":"boolean","description":"True if conversation state is persistent"},"createdAt":{"type":"string","description":"Conversation state created at"},"updatedAt":{"type":"string","description":"Conversation state created at"}},"required":["id","name","description","color","isPersistent","createdAt","updatedAt"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/conversations/states":{"get":{"description":"Fetches all available conversation states by agent API key.","operationId":"ExternalApiConversationsController_getConversationStates","parameters":[],"responses":{"200":{"description":"Successfully retrieved conversation states.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalApiGetConversationStateResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Get conversation states","tags":["Conversations","Agent API Key"]}}}}
```

## Get conversation by ID

> Fetches a conversation by its unique ID. The response includes the conversation details.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"ConversationWithFeedbacksResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"New conversation ID"},"conversationUserId":{"type":"string","description":"Conversation user ID"},"title":{"type":"string","description":"Conversation title"},"score":{"type":"number","description":"Conversation score"},"summary":{"type":"string","description":"Conversation summary"},"aiConversationId":{"type":"string","description":"AI conversation ID"},"metadata":{"type":"object","description":"Conversation metadata"},"aiCallId":{"type":"string","description":"AI call ID"},"mode":{"type":"string","description":"Conversation mode","enum":["manual","ai"]},"conversationStateId":{"type":"string","description":"Conversation state ID"},"user":{"description":"Conversation user","allOf":[{"$ref":"#/components/schemas/ExternalApiUserResponseDTO"}]},"createdAt":{"type":"string","description":"Date the conversation was created","format":"date-time"},"updatedAt":{"type":"string","description":"Date the conversation was updated","format":"date-time"},"assignedUser":{"description":"User the conversation is assigned to","nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/AssignedUserResponseDTO"}]},"feedbacks":{"description":"Conversation feedbacks","type":"array","items":{"$ref":"#/components/schemas/FeedbackResponseDTO"}}},"required":["id","conversationUserId","aiConversationId","user","createdAt","updatedAt"]},"ExternalApiUserResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"firstName":{"type":"string","description":"User first name"},"lastName":{"type":"string","description":"User last name"},"context":{"type":"string","description":"User context"},"source":{"type":"string","description":"User source"},"fkId":{"type":"string","description":"User fkId"},"fkUserId":{"type":"string","description":"User fkUserId"},"email":{"type":"string","description":"User email"},"phoneNumber":{"type":"string","description":"User phone number"},"metadata":{"type":"object","description":"Conversation user metadata"}},"required":["id","firstName","lastName"]},"AssignedUserResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Assigned user ID"},"firstName":{"type":"string","description":"Assigned user first name"},"lastName":{"type":"string","description":"Assigned user last name"},"avatarUrl":{"type":"string","description":"Assigned user avatar URL","nullable":true},"email":{"type":"string","description":"Assigned user email"},"phoneNumber":{"type":"string","description":"Assigned user phone number","nullable":true}},"required":["id","firstName","lastName","email"]},"FeedbackResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Feedback ID"},"voteType":{"type":"string","description":"Feedback vote type","enum":["up","down"]},"question":{"type":"string","description":"Feedback question","nullable":true},"answer":{"type":"string","description":"Feedback answer","nullable":true},"comment":{"type":"string","description":"Feedback comment","nullable":true},"userEmail":{"type":"string","description":"Email of the user who provided the feedback","nullable":true},"createdAt":{"type":"string","description":"Feedback created at"},"updatedAt":{"type":"string","description":"Feedback updated at"}},"required":["id","voteType","question","answer","comment","createdAt","updatedAt"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"EntityNotFoundErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":404},"name":{"type":"object","default":"ENTITY_NOT_FOUND_ERROR"},"message":{"type":"string","default":"ENTITY_NOT_FOUND"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/conversations/{id}":{"get":{"description":"Fetches a conversation by its unique ID. The response includes the conversation details.","operationId":"ExternalApiConversationsController_getConversationById","parameters":[{"name":"id","required":true,"in":"path","description":"The ID of the conversation to retrieve.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved the conversation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationWithFeedbacksResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Conversation not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Get conversation by ID","tags":["Conversations","Agent API Key"]}}}}
```

## Update conversation

> Updates an existing conversation by ID. Returns the updated conversation.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"UpdateConversationBodyDTO":{"type":"object","properties":{"title":{"type":"string","description":"Conversation title","maxLength":255},"context":{"type":"string","description":"Conversation context","maxLength":256000},"status":{"type":"string","description":"Conversation status","enum":["active","inactive","archived"]},"conversationStateId":{"type":"string","description":"Conversation state ID"}}},"ConversationResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"New conversation ID"},"conversationUserId":{"type":"string","description":"Conversation user ID"},"title":{"type":"string","description":"Conversation title"},"score":{"type":"number","description":"Conversation score"},"summary":{"type":"string","description":"Conversation summary"},"aiConversationId":{"type":"string","description":"AI conversation ID"},"metadata":{"type":"object","description":"Conversation metadata"},"aiCallId":{"type":"string","description":"AI call ID"},"mode":{"type":"string","description":"Conversation mode","enum":["manual","ai"]},"conversationStateId":{"type":"string","description":"Conversation state ID"},"user":{"description":"Conversation user","allOf":[{"$ref":"#/components/schemas/ExternalApiUserResponseDTO"}]},"createdAt":{"type":"string","description":"Date the conversation was created","format":"date-time"},"updatedAt":{"type":"string","description":"Date the conversation was updated","format":"date-time"},"assignedUser":{"description":"User the conversation is assigned to","nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/AssignedUserResponseDTO"}]}},"required":["id","conversationUserId","aiConversationId","user","createdAt","updatedAt"]},"ExternalApiUserResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"firstName":{"type":"string","description":"User first name"},"lastName":{"type":"string","description":"User last name"},"context":{"type":"string","description":"User context"},"source":{"type":"string","description":"User source"},"fkId":{"type":"string","description":"User fkId"},"fkUserId":{"type":"string","description":"User fkUserId"},"email":{"type":"string","description":"User email"},"phoneNumber":{"type":"string","description":"User phone number"},"metadata":{"type":"object","description":"Conversation user metadata"}},"required":["id","firstName","lastName"]},"AssignedUserResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Assigned user ID"},"firstName":{"type":"string","description":"Assigned user first name"},"lastName":{"type":"string","description":"Assigned user last name"},"avatarUrl":{"type":"string","description":"Assigned user avatar URL","nullable":true},"email":{"type":"string","description":"Assigned user email"},"phoneNumber":{"type":"string","description":"Assigned user phone number","nullable":true}},"required":["id","firstName","lastName","email"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"EntityNotFoundErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":404},"name":{"type":"object","default":"ENTITY_NOT_FOUND_ERROR"},"message":{"type":"string","default":"ENTITY_NOT_FOUND"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/conversations/{id}":{"put":{"description":"Updates an existing conversation by ID. Returns the updated conversation.","operationId":"ExternalApiConversationsController_updateConversation","parameters":[{"name":"id","required":true,"in":"path","description":"The ID of the conversation to update.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Details of the conversation to be updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateConversationBodyDTO"}}}},"responses":{"200":{"description":"Successfully updated the conversation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Conversation not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Update conversation","tags":["Conversations","Agent API Key"]}}}}
```

## Start a new conversation

> Start a new conversation using either an email, SMS or voice as the communication method. The response includes the conversation ID.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"StartEmailConversationBodyDTO":{"type":"object","properties":{"firstName":{"type":"string","description":"Conversation user first name"},"lastName":{"type":"string","description":"Conversation user last name"},"context":{"type":"string","description":"Conversation user context"},"conversationContext":{"type":"string","description":"Conversation context"},"source":{"type":"string","description":"Conversation user source"},"fkId":{"type":"string","description":"Conversation user fkId"},"fkUserId":{"type":"string","description":"Conversation user fkUserId"},"customData":{"type":"object","description":"Conversation custom data"},"conversationStateId":{"type":"string","description":"Conversation state ID"},"authorId":{"type":"string","description":"Author platform ID"},"skipPhoneNumberValidation":{"type":"boolean","description":"Skip phone number validation"},"skipEmailValidation":{"type":"boolean","description":"Skip email validation"},"channel":{"type":"string","description":"Conversation user preferred channel","enum":["email"]},"email":{"type":"string","description":"Conversation user email"},"emailSubject":{"type":"string","description":"Conversation user email subject"},"emailIntroduction":{"type":"string","description":"Conversation user email introduction"},"includeSignatureInEmail":{"type":"boolean","description":"Include email signature in the email"},"phoneNumber":{"type":"string","description":"User phone number"},"resetConversation":{"type":"boolean","description":"Archive current conversation and launch a new one","default":false}},"required":["firstName","lastName","channel","email","emailSubject","emailIntroduction"]},"StartSmsConversationBodyDTO":{"type":"object","properties":{"firstName":{"type":"string","description":"Conversation user first name"},"lastName":{"type":"string","description":"Conversation user last name"},"context":{"type":"string","description":"Conversation user context"},"conversationContext":{"type":"string","description":"Conversation context"},"source":{"type":"string","description":"Conversation user source"},"fkId":{"type":"string","description":"Conversation user fkId"},"fkUserId":{"type":"string","description":"Conversation user fkUserId"},"customData":{"type":"object","description":"Conversation custom data"},"conversationStateId":{"type":"string","description":"Conversation state ID"},"authorId":{"type":"string","description":"Author platform ID"},"skipPhoneNumberValidation":{"type":"boolean","description":"Skip phone number validation"},"skipEmailValidation":{"type":"boolean","description":"Skip email validation"},"channel":{"type":"string","description":"Conversation user preferred channel","enum":["sms"]},"phoneNumber":{"type":"string","description":"Conversation user phone number"},"smsIntroduction":{"type":"string","description":"Conversation user sms introduction"},"email":{"type":"string","description":"User email"},"resetConversation":{"type":"boolean","description":"Archive current conversation and launch a new one","default":false},"includeSignatureInSms":{"type":"boolean","description":"Include signature in SMS","default":false}},"required":["firstName","lastName","channel","phoneNumber","smsIntroduction"]},"StartVoiceConversationBodyDTO":{"type":"object","properties":{"firstName":{"type":"string","description":"Conversation user first name"},"lastName":{"type":"string","description":"Conversation user last name"},"context":{"type":"string","description":"Conversation user context"},"conversationContext":{"type":"string","description":"Conversation context"},"source":{"type":"string","description":"Conversation user source"},"fkId":{"type":"string","description":"Conversation user fkId"},"fkUserId":{"type":"string","description":"Conversation user fkUserId"},"customData":{"type":"object","description":"Conversation custom data"},"conversationStateId":{"type":"string","description":"Conversation state ID"},"authorId":{"type":"string","description":"Author platform ID"},"skipPhoneNumberValidation":{"type":"boolean","description":"Skip phone number validation"},"skipEmailValidation":{"type":"boolean","description":"Skip email validation"},"channel":{"type":"string","description":"Conversation user preferred channel","enum":["voice"]},"phoneNumber":{"type":"string","description":"Conversation user phone number"},"firstMessage":{"type":"string","description":"Assistant first message"},"email":{"type":"string","description":"User email"}},"required":["firstName","lastName","channel","phoneNumber","firstMessage"]},"StartConversationResponseDTO":{"type":"object","properties":{"conversationId":{"type":"string","description":"New conversation ID"}},"required":["conversationId"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/conversations/start":{"post":{"description":"Start a new conversation using either an email, SMS or voice as the communication method. The response includes the conversation ID.","operationId":"ExternalApiConversationsController_startConversation","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"discriminator":{"propertyName":"channel","mapping":{"email":"#/components/schemas/StartEmailConversationBodyDTO","sms":"#/components/schemas/StartSmsConversationBodyDTO","voice":"#/components/schemas/StartVoiceConversationBodyDTO"}},"oneOf":[{"$ref":"#/components/schemas/StartEmailConversationBodyDTO"},{"$ref":"#/components/schemas/StartSmsConversationBodyDTO"},{"$ref":"#/components/schemas/StartVoiceConversationBodyDTO"}]}}}},"responses":{"201":{"description":"Successfully start a new conversation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartConversationResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Start a new conversation","tags":["Conversations","Agent API Key"]}}}}
```

## Get conversation messages

> Fetches all messages associated with a specific conversation ID.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"GetConversationMessagesResponseDTO":{"type":"object","properties":{"messages":{"description":"List of conversation messages","type":"array","items":{"$ref":"#/components/schemas/ConversationMessageResponseDTO"}}},"required":["messages"]},"ConversationMessageResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Conversation message ID"},"message":{"type":"string","description":"Conversation message content"},"rawMessage":{"type":"string","description":"Raw message content"},"conversationId":{"type":"string","description":"Conversation ID"},"senderRole":{"type":"string","enum":["conversation_user","assistant","manual_assistant"],"description":"Sender role in the conversation"},"conversationMessageId":{"type":"string","description":"Question message ID"},"source":{"type":"string","enum":["email","sms","live_chat","copilot","api","voice"],"description":"Conversation source"},"createdAt":{"format":"date-time","type":"string","description":"Message create date"},"conversationMessageFeedbacks":{"description":"List of conversation message feedbacks","type":"array","items":{"$ref":"#/components/schemas/BaseFeedbackResponseDTO"}},"fullAIResponse":{"description":"Full AI response","allOf":[{"$ref":"#/components/schemas/FullAIResponseDTO"}]},"expandedMessage":{"type":"string","nullable":true,"description":"Expanded version of the message produced by Enhanced Prompting, if the skill is attached to the agent. Null when the skill is not attached or expansion was skipped."},"files":{"description":"Conversation message files","type":"array","items":{"$ref":"#/components/schemas/ConversationMessageFileResponseDTO"}}},"required":["id","message","conversationId","senderRole","conversationMessageId","source","createdAt"]},"BaseFeedbackResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Feedback ID"},"voteType":{"type":"string","description":"Feedback vote type","enum":["up","down"]},"question":{"type":"string","description":"Feedback question","nullable":true},"answer":{"type":"string","description":"Feedback answer","nullable":true},"comment":{"type":"string","description":"Feedback comment","nullable":true},"userEmail":{"type":"string","description":"Email of the user who provided the feedback","nullable":true}},"required":["id","voteType","question","answer","comment"]},"FullAIResponseDTO":{"type":"object","properties":{"reasoning":{"description":"Reasoning summaries","nullable":true,"type":"array","items":{"type":"string"}},"outputText":{"type":"string","description":"Output text","nullable":true},"urlCitations":{"description":"URL citations","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/UrlCitationDTO"}},"fileCitations":{"description":"File citations","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/FileCitationDTO"}}}},"UrlCitationDTO":{"type":"object","properties":{"url":{"type":"string","description":"URL"},"title":{"type":"string","description":"Title"}},"required":["url","title"]},"FileCitationDTO":{"type":"object","properties":{"fileId":{"type":"string","description":"File ID"},"filename":{"type":"string","description":"Filename"}},"required":["fileId","filename"]},"ConversationMessageFileResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"File ID"},"fileName":{"type":"string","description":"File name"},"openAIFileId":{"type":"string","description":"OpenAI file ID"},"size":{"type":"number","description":"File size","nullable":true},"updatedAt":{"format":"date-time","type":"string","description":"Updated at"},"createdAt":{"format":"date-time","type":"string","description":"Created at"}},"required":["id","fileName","openAIFileId","updatedAt","createdAt"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/conversations/{id}/messages":{"get":{"description":"Fetches all messages associated with a specific conversation ID.","operationId":"ExternalApiConversationsController_getConversationMessages","parameters":[{"name":"shouldIncludeFeedbacks","required":false,"in":"query","description":"If true, returns conversation messages with feedbacks","schema":{"type":"boolean"}},{"name":"orderDirection","required":false,"in":"query","description":"Message created at order direction. Default: ASC","schema":{"type":"string","enum":["ASC","DESC"]}},{"name":"id","required":true,"in":"path","description":"The ID of the conversation to retrieve messages for.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved conversation messages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetConversationMessagesResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Get conversation messages","tags":["Conversations","Agent API Key"]}}}}
```

## Send a message to an agent

> Send a new message to an agent using conversationId.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"ProcessMessageBodyDTO":{"type":"object","properties":{"message":{"type":"string","description":"The message that the user sends to the AI agent"},"context":{"type":"string","description":"Context of the message"},"files":{"description":"Files attached to the message","type":"array","items":{"$ref":"#/components/schemas/MessageFileBodyDTO"}}},"required":["message"]},"MessageFileBodyDTO":{"type":"object","properties":{"fileName":{"type":"string","description":"File name"},"storagePath":{"type":"string","description":"Storage path"}},"required":["fileName","storagePath"]},"ProcessMessageResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Conversation message ID"},"message":{"type":"string","description":"Conversation message content"},"rawMessage":{"type":"string","description":"Raw message content"},"conversationId":{"type":"string","description":"Conversation ID"},"senderRole":{"type":"string","enum":["conversation_user","assistant","manual_assistant"],"description":"Sender role in the conversation"},"conversationMessageId":{"type":"string","description":"Question message ID"},"source":{"type":"string","enum":["email","sms","live_chat","copilot","api","voice"],"description":"Conversation source"},"createdAt":{"format":"date-time","type":"string","description":"Message create date"},"conversationMessageFeedbacks":{"description":"List of conversation message feedbacks","type":"array","items":{"$ref":"#/components/schemas/BaseFeedbackResponseDTO"}},"fullAIResponse":{"description":"Full AI response","allOf":[{"$ref":"#/components/schemas/FullAIResponseDTO"}]},"expandedMessage":{"type":"string","nullable":true,"description":"Expanded version of the message produced by Enhanced Prompting, if the skill is attached to the agent. Null when the skill is not attached or expansion was skipped."},"files":{"description":"Conversation message files","type":"array","items":{"$ref":"#/components/schemas/ConversationMessageFileResponseDTO"}}},"required":["id","message","conversationId","senderRole","conversationMessageId","source","createdAt"]},"BaseFeedbackResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Feedback ID"},"voteType":{"type":"string","description":"Feedback vote type","enum":["up","down"]},"question":{"type":"string","description":"Feedback question","nullable":true},"answer":{"type":"string","description":"Feedback answer","nullable":true},"comment":{"type":"string","description":"Feedback comment","nullable":true},"userEmail":{"type":"string","description":"Email of the user who provided the feedback","nullable":true}},"required":["id","voteType","question","answer","comment"]},"FullAIResponseDTO":{"type":"object","properties":{"reasoning":{"description":"Reasoning summaries","nullable":true,"type":"array","items":{"type":"string"}},"outputText":{"type":"string","description":"Output text","nullable":true},"urlCitations":{"description":"URL citations","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/UrlCitationDTO"}},"fileCitations":{"description":"File citations","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/FileCitationDTO"}}}},"UrlCitationDTO":{"type":"object","properties":{"url":{"type":"string","description":"URL"},"title":{"type":"string","description":"Title"}},"required":["url","title"]},"FileCitationDTO":{"type":"object","properties":{"fileId":{"type":"string","description":"File ID"},"filename":{"type":"string","description":"Filename"}},"required":["fileId","filename"]},"ConversationMessageFileResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"File ID"},"fileName":{"type":"string","description":"File name"},"openAIFileId":{"type":"string","description":"OpenAI file ID"},"size":{"type":"number","description":"File size","nullable":true},"updatedAt":{"format":"date-time","type":"string","description":"Updated at"},"createdAt":{"format":"date-time","type":"string","description":"Created at"}},"required":["id","fileName","openAIFileId","updatedAt","createdAt"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/conversations/{id}/messages":{"post":{"description":"Send a new message to an agent using conversationId.","operationId":"ExternalApiConversationsController_processMessage","parameters":[{"name":"id","required":true,"in":"path","description":"The ID of the conversation to send a message to.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Provide conversationId and message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcessMessageBodyDTO"}}}},"responses":{"201":{"description":"Successfully processed a message to an agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcessMessageResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Send a message to an agent","tags":["Conversations","Agent API Key"]}}}}
```

## Send a message to an agent (async)

> Send a new message to an agent using conversationId.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"SendMessageBodyDTO":{"type":"object","properties":{"message":{"type":"string","description":"The message that the user sends to the AI agent"},"context":{"type":"string","description":"Context of the message"},"files":{"description":"Files attached to the message","type":"array","items":{"$ref":"#/components/schemas/MessageFileBodyDTO"}}},"required":["message"]},"MessageFileBodyDTO":{"type":"object","properties":{"fileName":{"type":"string","description":"File name"},"storagePath":{"type":"string","description":"Storage path"}},"required":["fileName","storagePath"]},"SendMessageResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Conversation message ID"},"message":{"type":"string","description":"Conversation message content"},"rawMessage":{"type":"string","description":"Raw message content"},"conversationId":{"type":"string","description":"Conversation ID"},"senderRole":{"type":"string","enum":["conversation_user","assistant","manual_assistant"],"description":"Sender role in the conversation"},"conversationMessageId":{"type":"string","description":"Question message ID"},"source":{"type":"string","enum":["email","sms","live_chat","copilot","api","voice"],"description":"Conversation source"},"createdAt":{"format":"date-time","type":"string","description":"Message create date"},"conversationMessageFeedbacks":{"description":"List of conversation message feedbacks","type":"array","items":{"$ref":"#/components/schemas/BaseFeedbackResponseDTO"}},"fullAIResponse":{"description":"Full AI response","allOf":[{"$ref":"#/components/schemas/FullAIResponseDTO"}]},"expandedMessage":{"type":"string","nullable":true,"description":"Expanded version of the message produced by Enhanced Prompting, if the skill is attached to the agent. Null when the skill is not attached or expansion was skipped."},"files":{"description":"Conversation message files","type":"array","items":{"$ref":"#/components/schemas/ConversationMessageFileResponseDTO"}}},"required":["id","message","conversationId","senderRole","conversationMessageId","source","createdAt"]},"BaseFeedbackResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Feedback ID"},"voteType":{"type":"string","description":"Feedback vote type","enum":["up","down"]},"question":{"type":"string","description":"Feedback question","nullable":true},"answer":{"type":"string","description":"Feedback answer","nullable":true},"comment":{"type":"string","description":"Feedback comment","nullable":true},"userEmail":{"type":"string","description":"Email of the user who provided the feedback","nullable":true}},"required":["id","voteType","question","answer","comment"]},"FullAIResponseDTO":{"type":"object","properties":{"reasoning":{"description":"Reasoning summaries","nullable":true,"type":"array","items":{"type":"string"}},"outputText":{"type":"string","description":"Output text","nullable":true},"urlCitations":{"description":"URL citations","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/UrlCitationDTO"}},"fileCitations":{"description":"File citations","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/FileCitationDTO"}}}},"UrlCitationDTO":{"type":"object","properties":{"url":{"type":"string","description":"URL"},"title":{"type":"string","description":"Title"}},"required":["url","title"]},"FileCitationDTO":{"type":"object","properties":{"fileId":{"type":"string","description":"File ID"},"filename":{"type":"string","description":"Filename"}},"required":["fileId","filename"]},"ConversationMessageFileResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"File ID"},"fileName":{"type":"string","description":"File name"},"openAIFileId":{"type":"string","description":"OpenAI file ID"},"size":{"type":"number","description":"File size","nullable":true},"updatedAt":{"format":"date-time","type":"string","description":"Updated at"},"createdAt":{"format":"date-time","type":"string","description":"Created at"}},"required":["id","fileName","openAIFileId","updatedAt","createdAt"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/conversations/{id}/messages/async":{"post":{"description":"Send a new message to an agent using conversationId.","operationId":"ExternalApiConversationsController_sendMessage","parameters":[{"name":"id","required":true,"in":"path","description":"The ID of the conversation to send a message to.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Provide conversationId and message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageBodyDTO"}}}},"responses":{"201":{"description":"Successfully sent a message to an agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Send a message to an agent (async)","tags":["Conversations","Agent API Key"]}}}}
```

## Get response on

> Fetches response on a specific conversation message ID.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"GetResponseOnResponseDTO":{"type":"object","properties":{"status":{"type":"string","enum":["pending","completed","failed"],"description":"Response status"},"message":{"description":"Response message","nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/ConversationMessageResponseDTO"}]},"error":{"type":"string","description":"Response error","nullable":true}},"required":["status","message","error"]},"ConversationMessageResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Conversation message ID"},"message":{"type":"string","description":"Conversation message content"},"rawMessage":{"type":"string","description":"Raw message content"},"conversationId":{"type":"string","description":"Conversation ID"},"senderRole":{"type":"string","enum":["conversation_user","assistant","manual_assistant"],"description":"Sender role in the conversation"},"conversationMessageId":{"type":"string","description":"Question message ID"},"source":{"type":"string","enum":["email","sms","live_chat","copilot","api","voice"],"description":"Conversation source"},"createdAt":{"format":"date-time","type":"string","description":"Message create date"},"conversationMessageFeedbacks":{"description":"List of conversation message feedbacks","type":"array","items":{"$ref":"#/components/schemas/BaseFeedbackResponseDTO"}},"fullAIResponse":{"description":"Full AI response","allOf":[{"$ref":"#/components/schemas/FullAIResponseDTO"}]},"expandedMessage":{"type":"string","nullable":true,"description":"Expanded version of the message produced by Enhanced Prompting, if the skill is attached to the agent. Null when the skill is not attached or expansion was skipped."},"files":{"description":"Conversation message files","type":"array","items":{"$ref":"#/components/schemas/ConversationMessageFileResponseDTO"}}},"required":["id","message","conversationId","senderRole","conversationMessageId","source","createdAt"]},"BaseFeedbackResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Feedback ID"},"voteType":{"type":"string","description":"Feedback vote type","enum":["up","down"]},"question":{"type":"string","description":"Feedback question","nullable":true},"answer":{"type":"string","description":"Feedback answer","nullable":true},"comment":{"type":"string","description":"Feedback comment","nullable":true},"userEmail":{"type":"string","description":"Email of the user who provided the feedback","nullable":true}},"required":["id","voteType","question","answer","comment"]},"FullAIResponseDTO":{"type":"object","properties":{"reasoning":{"description":"Reasoning summaries","nullable":true,"type":"array","items":{"type":"string"}},"outputText":{"type":"string","description":"Output text","nullable":true},"urlCitations":{"description":"URL citations","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/UrlCitationDTO"}},"fileCitations":{"description":"File citations","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/FileCitationDTO"}}}},"UrlCitationDTO":{"type":"object","properties":{"url":{"type":"string","description":"URL"},"title":{"type":"string","description":"Title"}},"required":["url","title"]},"FileCitationDTO":{"type":"object","properties":{"fileId":{"type":"string","description":"File ID"},"filename":{"type":"string","description":"Filename"}},"required":["fileId","filename"]},"ConversationMessageFileResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"File ID"},"fileName":{"type":"string","description":"File name"},"openAIFileId":{"type":"string","description":"OpenAI file ID"},"size":{"type":"number","description":"File size","nullable":true},"updatedAt":{"format":"date-time","type":"string","description":"Updated at"},"createdAt":{"format":"date-time","type":"string","description":"Created at"}},"required":["id","fileName","openAIFileId","updatedAt","createdAt"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/conversations/{id}/messages/{questionMessageId}/response-on":{"get":{"description":"Fetches response on a specific conversation message ID.","operationId":"ExternalApiConversationsController_getResponseOn","parameters":[{"name":"id","required":true,"in":"path","description":"The ID of the conversation to retrieve message for.","schema":{"type":"string"}},{"name":"questionMessageId","required":true,"in":"path","description":"The ID of the question message to retrieve response for. (The message that the user sent to the AI agent)","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved conversation message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetResponseOnResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Get response on","tags":["Conversations","Agent API Key"]}}}}
```

## Update conversation mode

> Updates conversation mode. Returns the updated conversation.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"UpdateConversationModeBodyDTO":{"type":"object","properties":{"mode":{"type":"string","description":"Conversation mode","enum":["manual","ai"]}}},"ConversationResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"New conversation ID"},"conversationUserId":{"type":"string","description":"Conversation user ID"},"title":{"type":"string","description":"Conversation title"},"score":{"type":"number","description":"Conversation score"},"summary":{"type":"string","description":"Conversation summary"},"aiConversationId":{"type":"string","description":"AI conversation ID"},"metadata":{"type":"object","description":"Conversation metadata"},"aiCallId":{"type":"string","description":"AI call ID"},"mode":{"type":"string","description":"Conversation mode","enum":["manual","ai"]},"conversationStateId":{"type":"string","description":"Conversation state ID"},"user":{"description":"Conversation user","allOf":[{"$ref":"#/components/schemas/ExternalApiUserResponseDTO"}]},"createdAt":{"type":"string","description":"Date the conversation was created","format":"date-time"},"updatedAt":{"type":"string","description":"Date the conversation was updated","format":"date-time"},"assignedUser":{"description":"User the conversation is assigned to","nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/AssignedUserResponseDTO"}]}},"required":["id","conversationUserId","aiConversationId","user","createdAt","updatedAt"]},"ExternalApiUserResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"firstName":{"type":"string","description":"User first name"},"lastName":{"type":"string","description":"User last name"},"context":{"type":"string","description":"User context"},"source":{"type":"string","description":"User source"},"fkId":{"type":"string","description":"User fkId"},"fkUserId":{"type":"string","description":"User fkUserId"},"email":{"type":"string","description":"User email"},"phoneNumber":{"type":"string","description":"User phone number"},"metadata":{"type":"object","description":"Conversation user metadata"}},"required":["id","firstName","lastName"]},"AssignedUserResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Assigned user ID"},"firstName":{"type":"string","description":"Assigned user first name"},"lastName":{"type":"string","description":"Assigned user last name"},"avatarUrl":{"type":"string","description":"Assigned user avatar URL","nullable":true},"email":{"type":"string","description":"Assigned user email"},"phoneNumber":{"type":"string","description":"Assigned user phone number","nullable":true}},"required":["id","firstName","lastName","email"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"EntityNotFoundErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":404},"name":{"type":"object","default":"ENTITY_NOT_FOUND_ERROR"},"message":{"type":"string","default":"ENTITY_NOT_FOUND"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/conversations/{id}/mode":{"put":{"description":"Updates conversation mode. Returns the updated conversation.","operationId":"ExternalApiConversationsController_updateConversationMode","parameters":[{"name":"id","required":true,"in":"path","description":"The ID of the conversation to update.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Details of the conversation mode to be updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateConversationModeBodyDTO"}}}},"responses":{"200":{"description":"Successfully updated the conversation mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Conversation not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Update conversation mode","tags":["Conversations","Agent API Key"]}}}}
```

## Send a manual message to a user

> Send a manual message to a user in a conversation that is in manual mode. Will fail if the conversation is not in manual mode or is a voice conversation.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"SendMessageToUserBodyDTO":{"type":"object","properties":{"message":{"type":"string","description":"The message that will be sent to the user"},"conversationMessageId":{"type":"string","description":"The ID of the conversation message that the user sent to the AI agent"},"authorId":{"type":"string","description":"Author platform ID"},"files":{"description":"Files attached to the message","type":"array","items":{"$ref":"#/components/schemas/MessageFileBodyDTO"}}},"required":["message"]},"MessageFileBodyDTO":{"type":"object","properties":{"fileName":{"type":"string","description":"File name"},"storagePath":{"type":"string","description":"Storage path"}},"required":["fileName","storagePath"]},"SendMessageResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Conversation message ID"},"message":{"type":"string","description":"Conversation message content"},"rawMessage":{"type":"string","description":"Raw message content"},"conversationId":{"type":"string","description":"Conversation ID"},"senderRole":{"type":"string","enum":["conversation_user","assistant","manual_assistant"],"description":"Sender role in the conversation"},"conversationMessageId":{"type":"string","description":"Question message ID"},"source":{"type":"string","enum":["email","sms","live_chat","copilot","api","voice"],"description":"Conversation source"},"createdAt":{"format":"date-time","type":"string","description":"Message create date"},"conversationMessageFeedbacks":{"description":"List of conversation message feedbacks","type":"array","items":{"$ref":"#/components/schemas/BaseFeedbackResponseDTO"}},"fullAIResponse":{"description":"Full AI response","allOf":[{"$ref":"#/components/schemas/FullAIResponseDTO"}]},"expandedMessage":{"type":"string","nullable":true,"description":"Expanded version of the message produced by Enhanced Prompting, if the skill is attached to the agent. Null when the skill is not attached or expansion was skipped."},"files":{"description":"Conversation message files","type":"array","items":{"$ref":"#/components/schemas/ConversationMessageFileResponseDTO"}}},"required":["id","message","conversationId","senderRole","conversationMessageId","source","createdAt"]},"BaseFeedbackResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Feedback ID"},"voteType":{"type":"string","description":"Feedback vote type","enum":["up","down"]},"question":{"type":"string","description":"Feedback question","nullable":true},"answer":{"type":"string","description":"Feedback answer","nullable":true},"comment":{"type":"string","description":"Feedback comment","nullable":true},"userEmail":{"type":"string","description":"Email of the user who provided the feedback","nullable":true}},"required":["id","voteType","question","answer","comment"]},"FullAIResponseDTO":{"type":"object","properties":{"reasoning":{"description":"Reasoning summaries","nullable":true,"type":"array","items":{"type":"string"}},"outputText":{"type":"string","description":"Output text","nullable":true},"urlCitations":{"description":"URL citations","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/UrlCitationDTO"}},"fileCitations":{"description":"File citations","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/FileCitationDTO"}}}},"UrlCitationDTO":{"type":"object","properties":{"url":{"type":"string","description":"URL"},"title":{"type":"string","description":"Title"}},"required":["url","title"]},"FileCitationDTO":{"type":"object","properties":{"fileId":{"type":"string","description":"File ID"},"filename":{"type":"string","description":"Filename"}},"required":["fileId","filename"]},"ConversationMessageFileResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"File ID"},"fileName":{"type":"string","description":"File name"},"openAIFileId":{"type":"string","description":"OpenAI file ID"},"size":{"type":"number","description":"File size","nullable":true},"updatedAt":{"format":"date-time","type":"string","description":"Updated at"},"createdAt":{"format":"date-time","type":"string","description":"Created at"}},"required":["id","fileName","openAIFileId","updatedAt","createdAt"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"EntityNotFoundErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":404},"name":{"type":"object","default":"ENTITY_NOT_FOUND_ERROR"},"message":{"type":"string","default":"ENTITY_NOT_FOUND"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/conversations/{id}/send-manual-message":{"post":{"description":"Send a manual message to a user in a conversation that is in manual mode. Will fail if the conversation is not in manual mode or is a voice conversation.","operationId":"ExternalApiConversationsController_sendManualMessage","parameters":[{"name":"id","required":true,"in":"path","description":"The ID of the conversation to send a message to the user.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Provide message to send to the user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageToUserBodyDTO"}}}},"responses":{"200":{"description":"Message sent successfully to the user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageResponseDTO"}}}},"400":{"description":"Conversation must be in manual mode and not a voice conversation."},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Conversation not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Send a manual message to a user","tags":["Conversations","Agent API Key"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.raiaai.com/api-reference/conversations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.