# 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"},"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"]},"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"}},"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"]},"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"},"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"]},"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"}},"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"]},"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"},"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"},"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"},"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"}]}},"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"]},"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"}},"required":["message"]},"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"}]}},"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"]},"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

> 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"}},"required":["message"]},"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"}]}},"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"]},"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","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,"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"}]}},"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"]},"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"}},"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"]},"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"}},"required":["message"]},"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"}]}},"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"]},"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"]}}}}
```