# Broker The broker API is responsible for managing the conversations performed by your users. While it is listed here, we encourage you to visit it's [specific page](https://docs.conversational-ai.syntphony.com/user-guide/api-docs/creating-channels-the-conversation-api#what-is-the-conversation-api) for a complete orientation of how to use it. ### Conversation Methods {% openapi src="" path="/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/channel/{channelUUID}/v1/conversations" method="post" %} [eva-broker-4.7.0.yaml](https://4008706377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6zS4HeuuVpRHZEvDiFU%2Fuploads%2FjDtCvq6alIqtj29o77bV%2Feva-broker-4.7.0.yaml?alt=media\&token=c0cd154d-8448-4ceb-94da-cf627a3bcf0c) {% endopenapi %} {% openapi src="" path="/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/channel/{channelUUID}/v1/conversations/{sessionCode}" method="post" %} [eva-broker-4.7.0.yaml](https://4008706377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6zS4HeuuVpRHZEvDiFU%2Fuploads%2FjDtCvq6alIqtj29o77bV%2Feva-broker-4.7.0.yaml?alt=media\&token=c0cd154d-8448-4ceb-94da-cf627a3bcf0c) {% endopenapi %} {% openapi src="" path="/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/conversations/{sessionCode}/satisfactions" method="post" %} [eva-broker-4.7.0.yaml](https://4008706377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6zS4HeuuVpRHZEvDiFU%2Fuploads%2FjDtCvq6alIqtj29o77bV%2Feva-broker-4.7.0.yaml?alt=media\&token=c0cd154d-8448-4ceb-94da-cf627a3bcf0c) {% endopenapi %} ### API Key ## GET /org/{orgUUID}/env/{envUUID}/api-key > Retrieves the API key for the specified organization and environment. ```json {"openapi":"3.0.1","info":{"title":"eva-broker API Documentation","version":"4.8.0"},"tags":[{"name":"Api Key","description":"Controller for managing API keys."}],"paths":{"/org/{orgUUID}/env/{envUUID}/api-key":{"get":{"tags":["Api Key"],"summary":"Retrieves the API key for the specified organization and environment.","operationId":"getApiKey","parameters":[{"name":"orgUUID","in":"path","description":"A valid organization UUID","required":true,"schema":{"type":"string"}},{"name":"envUUID","in":"path","description":"A valid environment UUID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiKeyDTO"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"408":{"description":"Request Timeout","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"422":{"description":"Unprocessable Entity","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/StandardError"}]}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}}}}}},"components":{"schemas":{"ApiKeyDTO":{"type":"object","properties":{"apiKey":{"type":"string"}}},"StandardError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/FieldMessage"}}}},"FieldMessage":{"type":"object","properties":{"fieldName":{"type":"string"},"message":{"type":"string"},"errorCode":{"type":"string"}}}}}} ``` ### Likable ## POST /org/{orgUUID}/env/{envUUID}/likable > Save user's evaluation ```json {"openapi":"3.0.1","info":{"title":"eva-broker API Documentation","version":"4.8.0"},"tags":[{"name":"Likable","description":"Controller for handling likable actions"}],"paths":{"/org/{orgUUID}/env/{envUUID}/likable":{"post":{"tags":["Likable"],"summary":"Save user's evaluation","operationId":"conversation","parameters":[{"name":"API-KEY","in":"header","description":"The API key from the request header for authorization","required":true,"schema":{"type":"string"}},{"name":"orgUUID","in":"path","description":"A valid organization UUID","required":true,"schema":{"type":"string"}},{"name":"envUUID","in":"path","description":"A valid environment UUID","required":true,"schema":{"type":"string"}},{"name":"requesterId","in":"query","description":"Query parameter for the requester ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LikableRequestBodyDTO"}}},"required":true},"responses":{"200":{"description":"Ok","content":{"*/*":{"schema":{"type":"string"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"408":{"description":"Request Timeout","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"422":{"description":"Unprocessable Entity","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/StandardError"}]}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}}}}}},"components":{"schemas":{"LikableRequestBodyDTO":{"type":"object","properties":{"evaluation":{"type":"boolean","description":"Indicates whether the interaction should be evaluated."},"interactionId":{"type":"string","description":"Unique identifier for the interaction."}},"description":"Contain customer satisfaction data"},"StandardError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/FieldMessage"}}}},"FieldMessage":{"type":"object","properties":{"fieldName":{"type":"string"},"message":{"type":"string"},"errorCode":{"type":"string"}}}}}} ``` ### History ## GET /org/{orgUUID}/env/{envUUID}/history/{businessKey} > Get conversation history ```json {"openapi":"3.0.1","info":{"title":"eva-broker API Documentation","version":"4.8.0"},"tags":[{"name":"History","description":"Controller for managing conversation history"}],"paths":{"/org/{orgUUID}/env/{envUUID}/history/{businessKey}":{"get":{"tags":["History"],"summary":"Get conversation history","operationId":"getHistory","parameters":[{"name":"businessKey","in":"path","description":"The business key to retrieve history","required":true,"schema":{"type":"string"}},{"name":"orgUUID","in":"path","description":"A valid organization UUID","required":true,"schema":{"type":"string"}},{"name":"envUUID","in":"path","description":"A valid environment UUID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/HistoryResponseDTO"}}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"408":{"description":"Request Timeout","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"422":{"description":"Unprocessable Entity","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/StandardError"}]}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}}}}}},"components":{"schemas":{"HistoryResponseDTO":{"type":"object","properties":{"session":{"$ref":"#/components/schemas/SessionDTO"},"userInteractions":{"type":"array","description":"A list of user interactions associated with the session.","items":{"$ref":"#/components/schemas/UserInteractionDTO"}}},"description":"Represents the response containing session and user interactions."},"SessionDTO":{"type":"object","properties":{"sessionCode":{"type":"string","description":"Unique code identifying the session"},"createDate":{"type":"string","description":"The date and time when the session was created","format":"date-time"},"expireDate":{"type":"string","description":"The date and time when the session will expire","format":"date-time"},"businessKey":{"type":"string","description":"Business key associated with the session"},"sessionType":{"type":"string","description":"Type of the session","enum":["CREATED","UPDATED","EXPIRED"]},"botId":{"type":"string","description":"Identifier for the bot associated with the session"},"channelId":{"type":"string","description":"Identifier for the communication channel"},"operatingSystem":{"type":"string","description":"Operating system on which the session is running"},"operatingSystemVersion":{"type":"string","description":"Version of the operating system"},"browser":{"type":"string","description":"Name of the web browser used"},"browserVersion":{"type":"string","description":"Version of the web browser being used"},"userRef":{"type":"string","description":"Reference identifier for the user"},"locale":{"type":"string","description":"Locale settings for the session"},"test":{"type":"boolean","description":"Indicates if this session is a test session"}},"description":"Representation of a session in the application"},"UserInteractionDTO":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the user interaction.","format":"int64"},"createDate":{"type":"string","description":"Date and time when the interaction was created.","format":"date-time"},"sessionCode":{"type":"string","description":"Code representing the user session."},"userSent":{"type":"boolean","description":"Indicates if the user sent the input."},"answerUuid":{"type":"string","description":"UUID corresponding to the answer provided."},"text":{"type":"string","description":"The text input provided by the user."},"intent":{"type":"string","description":"Intent inferred from the user input."},"confidence":{"type":"number","description":"Confidence level of the intent detection.","format":"double"},"entities":{"type":"string","description":"Entities extracted from the user's input."},"userSentId":{"type":"string","description":"Unique ID of the user who sent the input."},"evaluation":{"type":"boolean","description":"Indicates whether the interaction has been evaluated."},"uuid":{"type":"string","description":"UUID for the user interaction."}},"description":"Data transfer object for user interaction."},"StandardError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/FieldMessage"}}}},"FieldMessage":{"type":"object","properties":{"fieldName":{"type":"string"},"message":{"type":"string"},"errorCode":{"type":"string"}}}}}} ```