openapi: 3.0.1 info: title: Gladly Agents Conversations API version: '1.0' description: '# Introducing the Gladly API At Gladly, we believe that customer service is best when it''s a conversation. That means more than just helping customers with one-off questions or issues: it''s about making them feel known, valued, and respected for the individuals they are. The Gladly API was built to help facilitate those relationships, providing agents with the rich customer context they need to deliver seamless experiences that make customers feel like they''re more than just a number in a sea of others. # Overview You can integrate easily with Gladly by calling Gladly''s [REST API](#section/Overview/REST-API) and implementing the [Lookup API](#section/Overview/Lookup-API) to provide data from your own services. Some examples of what you do through Gladly APIs include managing customer profile data, interacting with a customer''s timeline, providing the latest information about a customer''s orders, and more. ## REST API Clients can access the **REST API** via HTTPS at your organization''s Gladly domain (e.g. `https://{organization}.gladly.com`). Resources follow REST semantics and utilize industry-standard HTTP verbs, response codes, and authentication schemes. In addition, all responses and payloads are in JSON with consistent error codes and formats. ## Lookup API The Gladly **Lookup API** allows your organization to provide data services to power the agent''s experience with a complete view of your customers'' information, transactions, and activity. You can provide a web service that implements the Lookup API and Gladly will call it when that data is needed. Like the REST API, the Lookup API is specified using REST semantics, and exchanges JSON requests and responses authenticated and signed with secure keys. Gladly will perform lookups when certain activities occur within Gladly, such as when a customer''s profile is loaded. A detailed overview of Lookup Adaptor architecture, requests, resposnes and more can be found [here](https://help.gladly.com/developer/docs/lookup-adapter-introduction). ## Testing Test the myriad possibilities of the Gladly API in a safe, secure space. We''ll enable the Gladly API in a separate sandbox environment, so you can experiment freely without impacting your production environment (or vice versa). Your sandbox environment is accessible at `https://{organization}.gladly.qa`, where `organization` is your company name. For specific API endpoints, see documentation below. # Getting Started Think of this section as getting the keys to unlocking your access to the Gladly APIs. First, you''ll need to set up an account with the necessary API [permissions](#/section/Getting-Started/Permissions). With these permissions, you can then go on to create the [API Token(s)](#section/Getting-Started/Creating-API-Tokens) you need to access Gladly''s API [resources](#section/Overview/Resources). ## Permissions Gladly Administrators can set API permissions on an agent-by-agent basis. We''ll discuss how this maps to API access in the section on [authentication](#section/Authentication) below. To allow a user to create API tokens and access the API: 1. Log in to your Gladly instance. 2. Open the menu on the top left-hand corner of the page. 3. Navigate to **Settings** > **Users* 4. Search and click the user profile you wish to give access to. 5. You''ll see a permission called **API User**. Select it, while making sure to keep the user''s **Agent** role intact. 6. Hit **Save** to give access. ![Agent profile screen](assets/permissions-agent.png) We recommend creating a dedicated user to make API calls, whose account won''t be used for agent and organization management. This will help you with any future audits of API activity vs. agent activity. ## Creating API Tokens You must create an API token to access Gladly API resources (see above [Permissions](#/section/Getting-Started/Permissions)). If your profile already has access to the **API User** permission, you''ll see a menu item titled **More settings**. Click **More settings**: ![API Token Menu](assets/permissions-token-nav.png) Click **API Tokens**, then the **Create Token** button on the upper right-hand corner of the page: ![API Token Add](assets/permissions-token-add.png) A token will be generated and named, by default, **New Token** (though depending on whether you have existing tokens, it may be named New Token 2, or New Token 3, etc.). You can rename the token to something more easily referenceable by clicking the name to edit. This token will be associated with your agent profile, which we refer to as the API User in this document. ![API Token View](assets/permissions-token-view.png) For security purposes, you''ll only see a new token once before you navigate away from the page. ## Replacing/Rotating API Tokens Should you lose this token, or wish to rotate your application keys, you can do the following: 1. Generate a new token. 2. Store the new token in a secure location. 3. Delete the old token. 4. Update your applications/scripts with the new token. # Authentication ' servers: - url: https://{organization}.gladly.com/api/v1 description: Production variables: organization: default: organization description: Your Gladly organization subdomain - url: https://{organization}.gladly.qa/api/v1 description: Sandbox variables: organization: default: organization description: Your Gladly QA organization subdomain security: - basicAuth: [] tags: - name: Conversations description: '## Conversation A **Conversation** in Gladly contains the timeline of activity for a customer including communications to and from your organization along with other internal and external activity. Conversations API enables you to interact with the customer conversation timeline. ## Conversation Items A number of different types of items may appear in a customer''s timeline. Each is described below. | Item Type | Item Definition | Create | Read | Update | Delete | Media | |-------------------------------|----------------|--------|------|--------|--------|--------| | Chat Message | A message sent/received via the [Chat](https://help.gladly.com/docs/add-and-configure-chat-entry-points#) channel | Yes | Yes | No | No | No | | Conversation Status Change | Conversation status changed (e.g.: from OPEN to WAITING, or OPEN to CLOSED) | Yes | Yes | Yes | No | No | | Customer Activity | Non-routable customer activity added to customer timeline via API | Yes | Yes | No | Yes | No | | Email | A message sent/received via the [Email](https://help.gladly.com/docs/add-and-configure-email-entry-point) channel | Yes | Yes | No | No | No | | Facebook Messenger Message | A message sent/received via the [Facebook Messenger](https://help.gladly.com/docs/set-up-and-configure-facebook-messenger) channel | Yes | Yes | No | No | No | | Instagram Direct | A message sent/received via the [Instagram](https://help.gladly.com/docs/set-up-and-configure-instagram-messaging) channel | No | Yes | No | No | No | | Note | An internal [Note](https://help.gladly.com/docs/add-a-note-to-a-conversation) on the Customer conversation | Yes | Yes | No | No | No | | Phone Call | A [Phone Call](https://help.gladly.com/docs/add-and-configure-voice-entry-points) placed/received on Gladly | No | Yes | No | No | Yes | | SMS Message | A message sent/received via the [SMS](https://help.gladly.com/docs/add-and-configure-sms-entry-points) channel | Yes | Yes | No | No | No | | Task | A [Task](https://help.gladly.com/docs/what-is-a-task) on a Customer''s profile | Yes | Yes | Yes | No | No | | Topic Change | A [Topic](https://help.gladly.com/docs/what-are-topics) added or removed on a Conversation | Yes | Yes | No | Yes | No | | Twitter (decommissioned as of 04/20/23) | A message sent/received via the [Twitter](https://help.gladly.com/docs/setup-and-configure-twitter-direct-messages) channel | No | Yes | No | Yes | No | | Voice AI Message | A spoken message exchanged with Gladly''s voice AI during a voice AI session | No | Yes | No | No | No | | Voicemail | A Voicemail received | No | Yes | No | No | Yes | | WhatsApp | A message sent/received via the WhatsApp channel | No | Yes | No | No | No | ### Chat Message Content of messages sent between Gladly and customers through Gladly Chat. ### Conversation Status Change Record of a change in the status of a conversation. ### Customer Activity Information about activities customers participated in, for example, emails they received, issues in another system, or customer satisfaction surveys they answered. These can be created through the API to bring in information from other systems. Adding an activity to the customer timeline is not customer facing. For example, posting an email activity to the timeline does not send an email to the customer. ![Customer Activity](assets/customer-activity.png) ### Email Content of emails sent between Gladly and customers. ### Facebook Messenger Message Content of messages sent between Gladly and customers on Facebook Messenger. ### Instagram Direct Content of messages sent between Gladly and customers on Instagram Direct. ### Note Content of the note recorded in Gladly. ### Phone Call Information about phone calls that took place between Gladly and customers. ### SMS Message Content of SMS text messages sent between Gladly and customers. To send SMS messages to customers through the API, see [Send SMS](#operation/sendSMS). ### Task Interacting with tasks through the conversations API is deprecated. Use [Tasks API](#tag/Tasks) instead. ### Topic Change Record of an agent adding or removing a topic from a conversation in Gladly. ### Twitter (decommissioned as of 04/20/23) Content of messages sent between Gladly and customers on Twitter. ### Voice AI Message A spoken message exchanged between a customer and Gladly''s voice AI during a voice AI session. ### Voicemail Information about voicemail left by customers in Gladly. ### WhatsApp Content of messages sent between Gladly and customers on WhatsApp. ' paths: /api/v1/customers/{customerId}/conversations: get: tags: - Conversations summary: Get Conversations for Customer description: 'Get the list of conversations for a customer. The list is not paginated and will return at most 100 conversations. The conversations are returned in ascending order by timestamp. The `Gladly-Limited-Data` header flag in the response will indicate if the customer has more conversations than returned. ' operationId: getConversations parameters: - in: path name: customerId schema: type: string required: true description: Id of the customer to get all conversations for example: gHufx-U3QqOmhvFuViceTw responses: '200': description: The conversations for the customer content: application/json: schema: title: Conversations type: array items: $ref: '#/paths/~1api~1v1~1conversations~1%7BconversationId%7D/get/responses/200/content/application~1json/schema' examples: Conversations: summary: Example of conversations response value: - id: HXRqKC5GSV-jAlq0-sxYTA topicIds: - _DZTz4I0Qsq9YXxeXwufMg - tYVmwhIVQe-2tflRIszQ3g customAttributes: - id: UCeBpdBVSNyaP54jhd8CZw value: '1234556777' - id: UCeBpdBVSNyaP54jhd8CZw value: '883399334403' - id: cEBkE90eQHObfcsnrm60Tg value: UPS customerId: o2sg-TMTSD2rTwMuxzewbA createdAt: '2016-01-02T00:10:00Z' agentId: sHuXx-U3QqOmhvFusJGeBw inboxId: E1nArq1uQAees_DogHB0MA status: OPEN - id: UMTZxwzJRyejwOj4NDfjeg topicIds: - tYVmwhIVQe-2tflRIszQ3g customAttributes: - id: UCeBpdBVSNyaP54jhd8CZw value: '1234556777' - id: UCeBpdBVSNyaP54jhd8CZw value: '883399334403' - id: cEBkE90eQHObfcsnrm60Tg value: UPS customerId: o2sg-TMTSD2rTwMuxzewbA createdAt: '2016-01-02T00:10:00Z' closedAt: '2016-01-03T08:10:00Z' agentId: sHuXx-U3QqOmhvFusJGeBw inboxId: E1nArq1uQAees_DogHB0MA status: CLOSED /api/v1/conversations/{conversationId}: get: tags: - Conversations summary: Get Conversation description: 'Get conversation metadata such as it''s assignee, topics, inbox, etc. ' operationId: getConversation parameters: - in: path name: conversationId schema: type: string required: true description: Id of the conversation to get example: 9BcE2O0DQ2ynGHRmk9FeoA responses: '200': description: Conversation metadata content: application/json: schema: title: Conversation type: object required: - id - customerId - createdAt - inboxId - status properties: id: type: string description: The id of the conversation example: pOVVdzweSumI4bFxjlT8LA customerId: type: string description: The id of the profile that this conversation belongs to example: gHufx-U3QqOmhvFuViceTw agentId: type: string description: The id of the agent who is assigned to the conversation example: sHuXx-U3QqOmhvFusJGeBw inboxId: type: string description: The id of the inbox to which the conversation belongs to example: E1nArq1uQAees_DogHB0MA customAttributes: type: array description: Custom attributes assigned to the conversation items: title: Custom Attribute description: Specifies a custom attribute type: object properties: id: type: string description: id of the custom attribute example: pOVVdzweSumI4bFxjlT8LA value: type: string description: value of the custom attribute example: '1234567890' topicIds: type: array description: Ids of topics assigned to the conversation items: type: string createdAt: type: string format: RFC3339 with millis description: Time the conversation was created example: '2016-04-11T14:09:23.000Z' closedAt: type: string format: RFC3339 with millis description: Time the conversation was closed. Only present if conversation is closed example: '2016-05-10T13:49:23.000Z' status: title: Conversation Status type: string enum: - OPEN - WAITING - CLOSED description: "Status of the conversation:\n * `OPEN` - conversation requires further action\n * `WAITING` - no further action from an agent required. Waiting for response from the customer\n * `CLOSED` - resolved and requiring no further action. It can be changed back to OPEN if customer needs further assistance\n" example: OPEN examples: Conversation: summary: Example of a conversation response value: id: HXRqKC5GSV-jAlq0-sxYTA topicIds: - _DZTz4I0Qsq9YXxeXwufMg - tYVmwhIVQe-2tflRIszQ3g customAttributes: - id: UCeBpdBVSNyaP54jhd8CZw value: '1234556777' - id: UCeBpdBVSNyaP54jhd8CZw value: '883399334403' - id: cEBkE90eQHObfcsnrm60Tg value: UPS customerId: o2sg-TMTSD2rTwMuxzewbA createdAt: '2016-01-02T00:10:00Z' closedAt: '2016-01-03T08:10:00Z' agentId: sHuXx-U3QqOmhvFusJGeBw inboxId: E1nArq1uQAees_DogHB0MA status: CLOSED '404': description: A conversation with the given id does not exist patch: tags: - Conversations summary: Update Conversation description: 'Update conversation assignee, statusor both ' operationId: patchConversation parameters: - in: path name: conversationId schema: type: string required: true description: Id of the conversation example: 9BcE2O0DQ2ynGHRmk9FeoA requestBody: required: true description: JSON representation of conversation updates content: application/json: schema: title: Conversation Update type: object properties: assignee: type: object title: Assignee Update required: - inboxId properties: agentId: type: string description: The id of the agent who is assigned to the conversation example: sHuXx-U3QqOmhvFusJGeBw inboxId: type: string description: The id of the inbox to which the conversation belongs to example: E1nArq1uQAees_DogHB0MA status: type: object title: Conversation Status required: - value properties: value: type: string description: Value of the status to change to enum: - CLOSED - OPEN force: type: boolean description: Determines whether to override the value if conversation still needs a response default: false example: assignee: inboxId: E1nArq1uQAees_DogHB0MA agentId: sHuXx-U3QqOmhvFusJGeBw status: value: CLOSED force: true responses: '204': description: updated conversation '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Errors' examples: some required fields are blank: value: errors: - attr: assignee.inboxId code: blank detail: '''inboxId'' cannot be blank when updating assignee' - attr: status.value code: blank detail: '''value'' cannot be blank when updating status' agent does not belong to inbox: value: errors: - attr: assignee.agentId code: invalid_state detail: agent does not belong to inbox reassigning closed conversation: value: errors: - code: invalid_state detail: closed conversation cannot be reassigned topics required before closing conversation: value: errors: - code: invalid_state detail: topics are required before closing of conversation customer waiting for response: value: errors: - code: invalid_state detail: cannot close conversation, customer waiting for response, set 'status.force' to true to override '404': description: A conversation with the given id does not exist content: application/json: schema: $ref: '#/components/schemas/Errors' example: errors: - code: not_exist detail: conversation does not exist /api/v1/conversation-items: post: tags: - Conversations summary: Create Item description: 'To add items to the timeline for a customer specified by identifying information. If the customer doesn''t exist, a new customer profile is created. Any items created using this API will not be considered part of a conversation, and are **non-routable** and **non-searchable** aside from the mobile phone number or email address specified as part of the payload. ' operationId: createItem requestBody: description: Conversation Item to create content: application/json: schema: title: Conversation Item To Create with Customer required: - content - customer type: object properties: id: maxLength: 50 type: string description: Unique conversation item id. Must be URL safe and under 50 characters. An id will be automatically generated if one is not included. example: pOVVdzweSumI4bFxjlT8LA customer: $ref: '#/paths/~1api~1v1~1tasks/post/requestBody/content/application~1json/schema/properties/customer' content: title: Conversation Item Content To Create oneOf: - title: Customer Activity description: An event such as consumer interaction outside Gladly that agents will see in the customer timeline. required: - activityType - type type: object properties: type: type: string example: CUSTOMER_ACTIVITY enum: - CUSTOMER_ACTIVITY title: maxLength: 100 type: string description: First line of highlighted text for the item in the customer timeline example: Welcome to Gladly! body: maxLength: 25000 type: string description: Plain text or rich content ([see here for supported markup](#tag/Rich-Content)) of the activity that will appear as the main content. example: At Gladly we set out to reinvent customer service. Why? Because 21st century consumers are different. They are from 18 to 80 years old, expect the brands they love to recognize them, and to be able to communicate with your agents over all channels – all the time. activityType: type: string description: Type of this activity. This will determine the icon displayed in the customer timeline. example: EMAIL enum: - EMAIL - ISSUE - SMS - SURVEY sourceName: maxLength: 50 type: string description: Name of the source system generating this activity example: HubSpot link: type: object properties: url: type: string description: URL for a clickable link that this item should go to example: https://www.gladly.com/product/ text: maxLength: 50 type: string description: Text label for the link example: View Details description: 'Clickable reference to appear at the bottom portion of the customer activity card in the customer timeline ' expandByDefault: type: boolean description: Whether the activity should be expanded by default in the customer timeline example: true default: false occurredAt: type: string description: 'Time when this activity occurred. Will determine where in the customer timeline this item appears. Limited to events no older than 1 year. Note if this value is not set, it will be ommitted from the GET Item API call, and ordering on the timeline will default to the `receivedAt` time (i.e.: `current_time`).' format: RFC3339 with millis example: '2016-04-11T14:09:23.000Z' receivedAt: type: string description: The time when this item was first sent to Gladly format: RFC3339 with millis readOnly: true example: '2019-01-11T20:49:55.000Z' - title: Task (deprecated) required: - body - dueAt - type - assignee type: object properties: type: type: string example: TASK enum: - TASK assignee: $ref: '#/paths/~1api~1v1~1tasks/post/requestBody/content/application~1json/schema/properties/assignee' body: maxLength: 10000 type: string description: Text to describe what task to complete. Constrained HTML [Rich Content](#tag/Rich-Content) is supported. example: Call customer back with information about booking dueAt: description: Time when the task will be due. This must be set to a time in the future. type: string format: RFC3339 example: '2020-03-15T06:13:00.125Z' attachments: type: array description: attachments to the task items: $ref: '#/paths/~1api~1v1~1conversations~1%7BconversationId%7D~1notes~1%7BnoteId%7D/get/responses/200/content/application~1json/schema/properties/content/properties/attachments/items' examples: Customer Activity: summary: Example of a Customer Activity value: id: pOVVdzweSumI4bFxjlT8LA customer: emailAddress: michelle.smith@example.org content: type: CUSTOMER_ACTIVITY title: Welcome to Gladly! body: At Gladly we set out to reinvent customer service. Why? Because 21st century consumers are different. They are from 18 to 80 years old, expect the brands they love to recognize them, and to be able to communicate with your agents over all channels – all the time. activityType: EMAIL sourceName: HubSpot link: url: https://www.gladly.com/product/ text: View Details required: true responses: '200': description: The created item content: application/json: schema: title: Conversation Item To Create type: object required: - content - timestamp properties: id: type: string description: the id of the item example: pOVVdzweSumI4bFxjlT8LA customerId: type: string description: the id of the profile that this item belongs to example: gHufx-U3QqOmhvFuViceTw timestamp: type: string format: RFC3339 description: Time the item occurred example: '2019-07-03T04:30:12.07Z' initiator: $ref: '#/paths/~1api~1v1~1tasks~1%7BtaskId%7D/get/responses/200/content/application~1json/schema/properties/createdBy' responder: title: Describes the communicator initiating or responding to the item type: object properties: id: type: string description: id of the communicator example: zGaHXjD4SR-moMR9LbULDa type: type: string description: 'type of communicator which can be an agent, customer, a person related to customer, rule, or application If an email response comes from a third-party recipient who was previously included in an email exchange with the customer (TO, CC, or BCC), the reply''s initiator type will be either ''INTERNAL'' or ''EXTERNAL'' depending on the sender''s email address domain. ''INTERNAL'' types are sent from email addresses that share domain with the agent''s organization. ''EXTERNAL'' types are sent from other domains. initiator.id=SIDEKICK_V2 and initiator.type=SYSTEM are set when the responder is Gladly AI. Note that Structured Threads (legacy) responses will still have initiator.type=API and initiator.id=API user ID associated with this token. ' enum: - AGENT - API - AUTOMATION - CUSTOMER - INTERNAL - EXTERNAL - SYSTEM example: AGENT content: $ref: '#/paths/~1api~1v1~1conversation-items/post/requestBody/content/application~1json/schema/properties/content' '400': description: Invalid field(s) in request body content: application/json: schema: $ref: '#/components/schemas/Errors' '409': description: Specified id is in use content: application/json: schema: $ref: '#/components/schemas/Errors' example: errors: - attr: newConversationItems code: taken detail: conversation item already exists /api/v1/conversation-items/{itemId}: get: tags: - Conversations summary: Get Item description: 'Returns the conversation item with the provided id. ' operationId: getItem parameters: - in: path name: itemId description: 'id of the conversation item ' schema: type: string example: pOVVdzweSumI4bFxjlT8LA required: true responses: '200': description: conversation item content: application/json: schema: title: Conversation Item type: object required: - id - customerId - content - timestamp properties: id: type: string description: the id of the item example: pOVVdzweSumI4bFxjlT8LA customerId: type: string description: the id of the profile that this item belongs to example: gHufx-U3QqOmhvFuViceTw conversationId: type: string description: id of the conversation the item is part of if it is within one example: PmDVUfWfRjKuwb4VgA2zEA sessionId: type: string description: session ID of the conversation example: 8K2mX9nRTyWv4bQzLpH5jA timestamp: type: string format: RFC3339 description: Time the item occurred example: '2019-07-03T04:30:12.07Z' initiator: $ref: '#/paths/~1api~1v1~1tasks~1%7BtaskId%7D/get/responses/200/content/application~1json/schema/properties/createdBy' responder: $ref: '#/paths/~1api~1v1~1conversation-items/post/responses/200/content/application~1json/schema/properties/responder' content: title: Conversation Item Content oneOf: - title: Chat Message oneOf: - title: Chat Message description: A text message sent during a Gladly chat session. type: object required: - type - sessionId - content - messageType properties: type: type: string enum: - CHAT_MESSAGE messageType: type: string enum: - TEXT sessionId: type: string description: id of the chat session the message is part of example: 5k04bYuTRGqyT6uoSQfWVA content: type: string description: text of the message sent example: HI! Can you help me with my order? attachments: type: array description: attachments to the message items: $ref: '#/paths/~1api~1v1~1conversations~1%7BconversationId%7D~1notes~1%7BnoteId%7D/get/responses/200/content/application~1json/schema/properties/content/properties/attachments/items' - title: Chat QuickReply Request description: A QuickReply request sent to a user during a Gladly chat session. type: object required: - type - sessionId - content - messageType - messageData properties: type: type: string enum: - CHAT_MESSAGE messageType: type: string enum: - QUICK_REPLY_REQUEST sessionId: type: string description: id of the chat session the message is part of example: 5k04bYuTRGqyT6uoSQfWVA content: type: string description: text of the message sent example: What can I help with? attachments: type: array description: attachments to the message items: $ref: '#/paths/~1api~1v1~1conversations~1%7BconversationId%7D~1notes~1%7BnoteId%7D/get/responses/200/content/application~1json/schema/properties/content/properties/attachments/items' messageData: type: object title: QuickReply request data description: Data that describes the QuickReply request options presented to the user properties: options: $ref: '#/paths/~1api~1v1~1conversation-items~1%7BitemId%7D~1reply/post/requestBody/content/application~1json/schema/properties/content/oneOf/1/oneOf/1/properties/messageData/properties/options' - title: Chat QuickReply response description: A response to a QuickReply request type: object required: - type - sessionId - content - messageType - messageData properties: type: type: string enum: - CHAT_MESSAGE messageType: type: string enum: - QUICK_REPLY_RESPONSE sessionId: type: string description: id of the chat session the message is part of example: 5k04bYuTRGqyT6uoSQfWVA content: type: string description: The label of the selected option example: Furniture attachments: type: array description: attachments to the message items: $ref: '#/paths/~1api~1v1~1conversations~1%7BconversationId%7D~1notes~1%7BnoteId%7D/get/responses/200/content/application~1json/schema/properties/content/properties/attachments/items' messageData: type: object title: QuickReplyResponse data description: Data that describes the users option selection properties: quickReplyRequest: type: object title: QuickReply Request description: The QuickReply request that this is a response to, for additional context. properties: options: $ref: '#/paths/~1api~1v1~1conversation-items~1%7BitemId%7D~1reply/post/requestBody/content/application~1json/schema/properties/content/oneOf/1/oneOf/1/properties/messageData/properties/options' selectedOptionId: type: string title: Selected option id description: The Id of the option the user selected requestMessageId: type: string title: message Id description: The id of the QuickReply request message that this is a response to - title: Conversation Status Change description: Record of a change in the status of a conversation type: object required: - type properties: type: type: string enum: - CONVERSATION_STATUS_CHANGE status: type: string description: Status of the conversation, where “OPEN” means conversation is assigned to an agent and “CLOSED” means the problem reported by the customer has been solved and the conversation requires no further action. Note that a conversation can be reopened, setting the status back to “OPEN”, if a customer responds to a closed conversation within a configurable time window. enum: - OPEN - CLOSED - $ref: '#/paths/~1api~1v1~1conversation-items/post/requestBody/content/application~1json/schema/properties/content/oneOf/0' - title: Email description: '' type: object required: - type - from - to - subject - content properties: type: type: string enum: - EMAIL from: type: string description: email address the message was from example: martha.williams@gmail.com to: type: array description: email addresses the message was sent to example: - martha.williams@gmail.com items: type: string cc: type: array description: email addresses the message was carbon copied to example: - billing@company.com items: type: string bcc: type: array description: email addresses the message was blind carbon copied to example: - supervisor@company.com items: type: string subject: type: string description: subject text of the email example: My order content: type: string description: plain text body of the email example: Part of my order was damaged. May I get a refund for those items? attachments: type: array description: attachments to the email items: $ref: '#/paths/~1api~1v1~1conversations~1%7BconversationId%7D~1notes~1%7BnoteId%7D/get/responses/200/content/application~1json/schema/properties/content/properties/attachments/items' - title: Facebook Messenger Message description: '' type: object required: - type - pageId - userId - content properties: type: type: string enum: - FACEBOOK_MESSAGE pageId: type: string description: Facebook page id userId: type: string description: Facebook user id for the communication content: type: string description: text of the message example: I love your brand! Do you have a loyalty program? attachments: type: array description: attachments to the message items: $ref: '#/paths/~1api~1v1~1conversations~1%7BconversationId%7D~1notes~1%7BnoteId%7D/get/responses/200/content/application~1json/schema/properties/content/properties/attachments/items' - $ref: '#/paths/~1api~1v1~1conversations~1%7BconversationId%7D~1notes~1%7BnoteId%7D/get/responses/200/content/application~1json/schema/properties/content' - title: Phone Call description: Record of a phone call between a customer and an agent type: object required: - type - from - to - startedAt properties: type: type: string enum: - PHONE_CALL from: type: string format: E.164 description: phone number of the caller example: '+14153335555' to: type: string format: E.164 description: phone number call was to example: '+12149897676' startedAt: type: string format: RFC3339 description: time the phone call started example: '2019-07-02T08:05:00.10Z' answeredAt: type: string format: RFC3339 description: time the phone call was answered example: '2019-07-02T08:05:09.41Z' completedAt: type: string format: RFC3339 description: time the phone call ended example: '2019-07-02T08:11:15.03Z' recordingStatus: type: string description: 'Status of the phone call recording.
AVAILABLE : Recording is available for download
DELETED : Recording was deleted by the user
ERROR : An error occurred while recording. Please contact Gladly Support Team' enum: - AVAILABLE - DELETED - ERROR recordingUrl: type: string description: URL to retrieve media for the phone call recording in single-channel 32-kbps MP3 format. Present if recording is “AVAILABLE” recordingDuration: type: integer description: Duration of the phone call recording in seconds. Present if recording is “AVAILABLE” example: 44 recordingSummary: title: Recording Summary description: Summary of the voice recording type: object properties: status: type: string description: 'Status of the voice recoding summary.
FAILED : An error occurred while trying to summarize a voice recording
READY : Recording summary is available
PENDING : Trying to summarize a voice recording
REDACTED : An associated recording has been deleted' enum: - FAILED - READY - PENDING - REDACTED example: READY summary: type: string description: Voice recording summary text example: The customer calls to exchange an item. The representative asks for the customer's details and explains that the return process is different for each situation. The customer decides to reorder the correct size and thanks the representative for their help. language: type: string description: Language example: en - title: SMS Message description: A message sent via SMS type: object required: - type - from - to - content properties: type: type: string enum: - SMS from: type: string format: E.164 description: phone number of SMS sender example: '+14153335555' to: type: string format: E.164 description: phone number of SMS receiver example: '+12149897676' content: type: string description: text of the SMS message example: I haven't received my order yet. Can you check on the status? attachments: type: array description: attachments to the message items: $ref: '#/paths/~1api~1v1~1conversations~1%7BconversationId%7D~1notes~1%7BnoteId%7D/get/responses/200/content/application~1json/schema/properties/content/properties/attachments/items' - title: Topic Change description: Record of an agent applying or removing a topic from the conversation type: object required: - type properties: type: type: string enum: - TOPIC_CHANGE addedTopicIds: type: array description: ids of topics added to the conversation items: type: string example: uu4t00vITaKQ3bVjU2UrGQ removedTopicIds: type: array description: ids of topics removed from the conversation items: type: string example: uu4t00vITaKQ3bVjU2UrGQ - title: Voice AI Message description: A spoken message exchanged between a customer and Gladly's voice AI during a voice AI session. The item's `sessionId` identifies the voice AI session. type: object required: - type - companyNumber - body properties: type: type: string enum: - VOICE_AI_MESSAGE customerNumber: type: string format: E.164 description: Phone number of the customer participating in the voice AI session example: '+14153335555' companyNumber: type: string format: E.164 description: Phone number the customer dialed to reach the voice AI session example: '+12149897676' body: type: string description: Text of the spoken message example: Thanks for calling. How can I help you today? status: type: string description: "Delivery status of a voice AI message spoken to the customer:\n * `PLAYED` - the message was played to the customer in full\n * `INTERRUPTED` - the customer interrupted the message before it finished playing\n" enum: - PLAYED - INTERRUPTED example: PLAYED - title: Voicemail description: Record of a voicemail left by customer in Gladly type: object required: - type properties: type: type: string enum: - VOICEMAIL startedAt: description: Start time of the voicemail type: string format: RFC3339 example: '2020-03-15T06:13:00.125Z' recordingStatus: type: string description: 'Status of the voicemail recording
AVAILABLE : Recording is available for download
DELETED : Recording was deleted by the user
ERROR : An error occurred while recording. Please contact Gladly Support Team' enum: - AVAILABLE - DELETED - ERROR recordingUrl: type: string description: URL to retrieve media for the voicemail in single-channel 32-kbps MP3 format. Present if recording status is “AVAILABLE” recordingDuration: type: integer description: Duration of the voicemail in seconds. Present if recording status is “AVAILABLE” example: 44 recordingSummary: $ref: '#/paths/~1api~1v1~1conversation-items~1%7BitemId%7D/get/responses/200/content/application~1json/schema/properties/content/oneOf/6/properties/recordingSummary' - title: WhatsApp Message description: '' type: object required: - type - content properties: type: type: string enum: - WHATSAPP content: type: string description: text of the message example: I love your brand! Do you have a loyalty program? attachments: type: array description: attachments to the message items: $ref: '#/paths/~1api~1v1~1conversations~1%7BconversationId%7D~1notes~1%7BnoteId%7D/get/responses/200/content/application~1json/schema/properties/content/properties/attachments/items' - title: Instagram Message description: '' type: object required: - type - content properties: type: type: string enum: - INSTAGRAM_DIRECT content: type: string description: text of the message example: I love your brand! Do you have a loyalty program? attachments: type: array description: attachments to the message items: $ref: '#/paths/~1api~1v1~1conversations~1%7BconversationId%7D~1notes~1%7BnoteId%7D/get/responses/200/content/application~1json/schema/properties/content/properties/attachments/items' - title: Twitter Message (decommissioned as of 04/20/23 but can still be retrieved) description: '' type: object required: - type - content properties: type: type: string enum: - TWITTER content: type: string description: text of the message example: I love your brand! Do you have a loyalty program? '400': description: An item exists but is not supported by the API content: application/json: schema: $ref: '#/components/schemas/Errors' example: errors: - code: invalid detail: Conversation item with id [pOVVdzweSumI4bFxjlT8LA] exists but is not supported by the API. '404': description: An item with the given id could not be found delete: tags: - Conversations summary: Delete Item description: 'To delete an item. Please note only items of type **CUSTOMER_ACTIVITY** may be deleted by this API. ' operationId: deleteItem parameters: - in: path name: itemId schema: type: string required: true description: 'Id of the item to be deleted. ' responses: '204': description: The item was deleted '404': description: An item with the given id could not be found /api/v1/conversation-items/{itemId}/media/recording: get: tags: - Conversations summary: Get Media description: 'Returns the media file associated with the conversation item ' operationId: getMedia parameters: - in: path name: itemId description: 'id of the conversation item ' schema: type: string example: pOVVdzweSumI4bFxjlT8LA required: true responses: '200': description: The media file associated with the conversation item content: audio/mpeg: schema: type: string format: binary description: Single channel 32-kbps MP3 audio file '404': description: An item with the given id could not be found /api/v1/conversation-items/{itemId}/voice-transcript: get: tags: - Conversations summary: Get Voice Transcript description: 'Returns a transcript of a phone call or a voicemail ' operationId: getVoiceTranscript parameters: - in: path name: itemId description: 'id of the conversation item ' schema: type: string example: pOVVdzweSumI4bFxjlT8LA required: true responses: '200': description: The voice transcript of a phone call or a voicemail content: application/json: schema: title: Voice Transcript description: Transcript of a voice recording type: object properties: paragraphs: type: array description: Paragraphs items: description: Paragraph type: object properties: transcript: type: string description: Transcript text example: Hello! How are you doing today? speaker: type: integer description: Speaker number example: 0 startTime: type: number description: Start time of the paragraph (in seconds from the beginning of the recording) example: 2.48 endTime: type: number description: End time of the paragraph (in seconds from the beginning of the recording) example: 6.1 customerId: type: string description: Customer associated with the voice transcript example: AloLvEkzQlqc7c4kyYQY1A numberOfSpeakers: type: integer description: Number of speakers example: 1 language: type: string description: Language createdAt: type: string format: RFC3339 with millis description: Time the voice transcript was created example: '2024-05-15T14:09:23.000Z' updatedAt: type: string format: RFC3339 with millis description: Time the voice transcript was updated example: '2024-05-15T14:19:23.000Z' '404': description: A transcript with the given id could not be found /api/v1/conversation-items/{itemId}/attachments/{attachmentId}: get: tags: - Conversations summary: Get Attachment description: 'Returns a redirect to the URL of the specified attachment on a conversation item. The response is a `303 See Other` redirect. Follow the redirect to download the attachment content. Attachments are available on conversation items with content types that support them, such as emails, chat messages, SMS messages, and custom channel messages. ' operationId: getAttachment parameters: - in: path name: itemId schema: type: string example: pOVVdzweSumI4bFxjlT8LA required: true description: 'Id of the conversation item that contains the attachment. ' - in: path name: attachmentId schema: type: string example: dGhpcyBpcyBhbiBhdHRhY2htZW50 required: true description: 'Id of the attachment to retrieve. ' responses: '303': description: Redirect to the attachment URL headers: Location: schema: type: string description: 'URL to download the attachment content. ' '400': description: The conversation item content does not contain attachments content: application/json: schema: $ref: '#/components/schemas/Errors' example: errors: - code: invalid detail: conversation item content does not contain attachments '404': description: The conversation item or attachment could not be found /api/v1/customers/{customerId}/conversation-items: post: tags: - Conversations summary: Create Item for Customer description: 'To add items to a customer''s timeline. Any items created using this API will not be considered part of a conversation, and are **non-routable** and **non-searchable** aside from the mobile phone number or email address specified as part of the payload. ' operationId: createCustomerItem parameters: - in: path name: customerId schema: type: string required: true description: 'Id of the customer associated with this item. You can look up the id using the [Find customers](index.html#tag/Customers) API. ' requestBody: description: Conversation Item to create content: application/json: schema: title: Conversation Item To Create required: - content type: object properties: id: maxLength: 50 type: string description: Unique conversation item id. Must be URL safe and under 50 characters. An id will be automatically generated if one is not included. example: pOVVdzweSumI4bFxjlT8LA content: $ref: '#/paths/~1api~1v1~1conversation-items/post/requestBody/content/application~1json/schema/properties/content' examples: Customer Activity: summary: Example of a Customer Activity value: content: type: CUSTOMER_ACTIVITY title: Welcome to Gladly! body: At Gladly we set out to reinvent customer service. Why? Because 21st century consumers are different. They are from 18 to 80 years old, expect the brands they love to recognize them, and to be able to communicate with your agents over all channels – all the time. activityType: EMAIL sourceName: HubSpot link: url: https://www.gladly.com/product/ text: View Details responses: '200': description: The created item content: application/json: schema: $ref: '#/paths/~1api~1v1~1conversation-items/post/responses/200/content/application~1json/schema' '301': description: This customer id no longer exists, but has been moved because it has been merged with another customer headers: Location: schema: type: string example: https://example.gladly.com/api/v1/customers/TX6f82W4S_ayp11kP4dhrQ/conversation-items description: Location of the new customer id to use content: application/json: schema: $ref: '#/components/schemas/Errors' example: errors: - attr: customer id code: moved detail: the customer id has changed from [wjotRA-fSU6feGCxdFwwNQ] to [TX6f82W4S_ayp11kP4dhrQ] meta: old: wjotRA-fSU6feGCxdFwwNQ new: TX6f82W4S_ayp11kP4dhrQ '400': description: Invalid field(s) in request body content: application/json: schema: $ref: '#/components/schemas/Errors' '404': description: Customer with customerId does not exist '409': description: Specified id is in use content: application/json: schema: $ref: '#/components/schemas/Errors' example: errors: - attr: newConversationItems code: taken detail: conversation item already exists /api/v1/customers/{customerId}/conversation-items/{itemId}: delete: tags: - Conversations summary: Delete Item for Customer description: 'To delete an item. Please note only items of type **CUSTOMER_ACTIVITY** may be deleted by this API. ' operationId: deleteCustomerItem parameters: - in: path name: customerId schema: type: string required: true description: 'Id of the customer associated with this item. You can look up the id using the [Find customers](index.html#tag/Customers) API. ' - in: path name: itemId schema: type: string required: true description: 'Id of the item to be deleted. ' responses: '204': description: The item was deleted '404': description: An item with the given id, for the given customer id, could not be found /api/v1/conversations/{conversationId}/items: get: tags: - Conversations summary: List Items in Conversation description: 'Get the list of items in the timeline of a conversation. The conversation represents a period of related interactions between a customer and your organization. The list is not paginated and will return at most 1000 items. The items are returned in ascending order by timestamp. The `Gladly-Limited-Data` header flag in the response will indicate if the conversation has more items than returned. The response can be filtered by session using the optional `sessionId` query parameter. ' operationId: getConversationItems parameters: - in: path name: conversationId schema: type: string required: true description: Id of the conversation to get the timeline for example: 9BcE2O0DQ2ynGHRmk9FeoA - in: query name: sessionId schema: type: string required: false description: Return only items whose `sessionId` matches the given value. example: 5k04bYuTRGqyT6uoSQfWVA responses: '200': description: The items on the conversation timeline content: application/json: schema: title: Conversation Items type: array items: $ref: '#/paths/~1api~1v1~1conversation-items~1%7BitemId%7D/get/responses/200/content/application~1json/schema' examples: Conversation Items: summary: Example of conversation items response value: - id: ybP4szYCSy6LdV4DNwEd6g conversationId: 9BcE2O0DQ2ynGHRmk9FeoA customerId: OOrlNMXeS72gs_WEX2TtMg timestamp: '2019-07-01T11:46:45.01Z' initiator: id: OOrlNMXeS72gs_WEX2TtMg type: CUSTOMER content: type: CHAT_MESSAGE sessionId: 5k04bYuTRGqyT6uoSQfWVA content: Hi! I know it's after hours but can someone help upgrade my account? - id: Rk7dLm2xTXqNwZp8vB3YeA conversationId: 9BcE2O0DQ2ynGHRmk9FeoA customerId: OOrlNMXeS72gs_WEX2TtMg timestamp: '2019-07-01T11:46:50.01Z' initiator: id: SIDEKICK_V2 type: SYSTEM content: type: CHAT_MESSAGE sessionId: 5k04bYuTRGqyT6uoSQfWVA content: Hello! I can help you with upgrading your account. What plan are you interested in? - id: 9lQDrx-HTz-JMoP2T4CtZA conversationId: 9BcE2O0DQ2ynGHRmk9FeoA customerId: OOrlNMXeS72gs_WEX2TtMg timestamp: '2019-07-02T06:30:12.07Z' initiator: id: WmeA3Y51Q5ayCAaZ1AotIA type: AGENT content: type: EMAIL from: amy.agent@company.com to: - martha.williams@gmail.com subject: Account upgrade content: I would be happy to help you! We need a few details, so please give us a call this morning. - id: S6pMkJ78QMmkVf9qPP_SeQ conversationId: 9BcE2O0DQ2ynGHRmk9FeoA customerId: OOrlNMXeS72gs_WEX2TtMg timestamp: '2019-07-02T08:05:00.10Z' initiator: id: OOrlNMXeS72gs_WEX2TtMg type: CUSTOMER responder: id: WmeA3Y51Q5ayCAaZ1AotIA type: AGENT content: type: PHONE_CALL from: '+14153335555' to: '+12149897676' startedAt: '2019-07-02T08:05:00.10Z' answeredAt: '2019-07-02T08:05:09.41Z' completedAt: '2019-07-02T08:11:15.03Z' recordingStatus: AVAILABLE recordingUrl: /api/v1/conversation-items/S6pMkJ78QMmkVf9qPP_SeQ/media/recording recordingDuration: '100' - id: K0UGL3n6S4uPpvtMvItqHA conversationId: 9BcE2O0DQ2ynGHRmk9FeoA customerId: OOrlNMXeS72gs_WEX2TtMg timestamp: '2019-07-02T08:12:55.870Z' initiator: id: WmeA3Y51Q5ayCAaZ1AotIA type: AGENT content: type: TOPIC_CHANGE addedTopicIds: - uu4t00vITaKQ3bVjU2UrGQ - id: zwo9AtljSfaGjWb4Aq-aDQ conversationId: WmeA3Y51Q5ayCAaZ1AotIA customerId: o2sg-TMTSD2rTwMuxzewbA timestamp: '2019-07-02T08:12:55.870Z' initiator: id": zGaHXjD4SR-moMR9LbULDA type": AGENT content: type: CONVERSATION_STATUS_CHANGE status: CLOSED - id: azwo9AtljSfaGjWb4Aq-aDQ conversationId: WmeA3Y51Q5ayCAaZ1AotIA customerId: o2sg-TMTSD2rTwMuxzewbA timestamp: '2019-07-02T08:12:55.870Z' initiator: id": zGaHXjD4SR-moMR9LbULDA type": AGENT content: type: VOICEMAIL startedAt: '2019-07-04T08:12:55.870Z' recordingUrl: /api/v1/conversation-items/azwo9AtljSfaGjWb4Aq-aDQ/media/recording recordingStatus: AVAILABLE recordingDuration: 200 - id: VnL3kQ8zSPmW9rXpA2fYbA conversationId: 9BcE2O0DQ2ynGHRmk9FeoA customerId: OOrlNMXeS72gs_WEX2TtMg sessionId: 8K2mX9nRTyWv4bQzLpH5jA timestamp: '2019-07-02T08:13:02.450Z' initiator: id: SIDEKICK_V2 type: SYSTEM content: type: VOICE_AI_MESSAGE customerNumber: '+14153335555' companyNumber: '+12149897676' body: Thanks for calling. How can I help you today? status: PLAYED - id: DnaU23pZSIqOixATlII1vA conversationId: HXRqKC5GSV-jAlq0-sxYTA customerId: o2sg-TMTSD2rTwMuxzewbA timestamp: '2019-07-04T23:42:57.780Z' initiator: type: AGENT id: zGaHXjD4SR-moMR9LbULDA content: type: CONVERSATION_NOTE body: Customer has requested more information about our loyalty program. '404': description: A conversation with the given id does not exist /api/v1/conversations/{conversationId}/topics: post: tags: - Conversations summary: Add Topics to Conversation description: 'Adds a list of topics to the conversation. If a topic being added already exists on the conversation, that topic is ignored. ' operationId: addTopicToConversation parameters: - in: path name: conversationId schema: type: string required: true description: 'Id of the conversation. ' requestBody: content: application/json: schema: title: List of Conversation Topics to Add required: - topicIDs type: object properties: topicIds: type: array example: - pOVVdzweSumI4bFxjlT8LA items: type: string description: Topic Ids to be added to the conversation. examples: Conversation Topic: summary: Example of a Conversation Topic value: topicIds: - pOVVdzweSumI4bFxjlT8LA - pOVVdzweSumI4bFxjlT8LB required: true responses: '204': description: The topic was added successfully '400': description: Invalid field(s) in request body content: application/json: schema: $ref: '#/components/schemas/Errors' '404': description: A conversation with the given Id could not be found /api/v1/conversations/{conversationId}/topics/{topicId}: delete: tags: - Conversations summary: Delete Topic From Conversation description: 'Delete a topic from a conversation. ' operationId: deleteTopicFromConversation parameters: - in: path name: conversationId schema: type: string required: true description: 'Id of the conversation. ' - in: path name: topicId schema: type: string required: true description: 'Id of topic to be deleted from conversation. ' responses: '204': description: The topic was deleted from the conversation successfully '404': description: A conversation with the given id could not be found /api/v1/customer-history/{customerId}/conversations/{conversationId}/custom-attributes: post: tags: - Conversations summary: Add or Remove Freeform Topic description: 'Adds or removes a list of freeform topics to the conversation. If the freeform topic being added already exists on the conversation, that topic is ignored. ' parameters: - in: path name: customerId schema: type: string required: true description: 'Id of the customer. ' - in: path name: conversationId schema: type: string required: true description: 'Id of the conversation. ' requestBody: content: application/json: schema: title: List of Conversation Freeform Topics to Add or Remove required: - content type: object properties: body: type: string items: type: object description: Freeform topics that need to be added or removed from a conversation examples: Custom Attributes: summary: Example of a Conversation Freeform Topic Add or Remove value: add: - key: ORDER_ID value: ORD_3 - key: ORDER_ID value: ORD_4 remove: - key: ORDER_ID value: ORD_1 - key: ORDER_ID value: ORD_2 required: true responses: '204': description: The freeform topic was added successfully '400': description: Invalid field(s) in request body content: application/json: schema: $ref: '#/components/schemas/NotFoundErrors' '404': description: A conversation with the given Id could not be found /api/v1/conversations/{conversationId}/notes: post: tags: - Conversations summary: Add Note description: Adds note to an existing conversation. operationId: addNoteToConversation parameters: - in: path name: conversationId schema: type: string required: true description: 'Id of the conversation. ' requestBody: content: application/json: schema: title: Content of note to add required: - content type: object properties: body: type: string description: Plain text or [rich content ](#tag/Rich-Content) of the note. example:

Customer has requested more information about our loyalty program.

examples: Conversation Note: summary: Example of a Conversation Note value: content: body: Customer has requested more information about our loyalty program. responses: '201': description: The note was added successfully headers: Location: schema: description: Relative URL of the created note example: /api/v1/conversations/cHBetnP5QYiwg-rvfaVDAQ/notes/HVFDjpu1SCKJlDR7rRKkCQ '400': description: Invalid field(s) in request body content: application/json: schema: $ref: '#/components/schemas/Errors' '404': description: A conversation with the given Id could not be found /api/v1/conversations/{conversationId}/notes/{noteId}: get: tags: - Conversations summary: Get Note description: 'Returns the note with the provided conversation and note id. ' operationId: getNoteFromConversation parameters: - in: path name: conversationId description: 'id of the conversation ' schema: type: string example: pOVVdzweSumI4bFxjlT8LA required: true - in: path name: noteId description: 'id of the note ' schema: type: string example: aOVVdzweSumI4bFxjlT8LA required: true responses: '200': description: Conversation note content: application/json: schema: title: Conversation Note type: object required: - id - customerId - content - timestamp properties: id: type: string description: the id of the item example: pOVVdzweSumI4bFxjlT8LA customerId: type: string description: the id of the customer profile that this item belongs to example: gHufx-U3QqOmhvFuViceTw conversationId: type: string description: id of the conversation the item is part of if it is within one example: PmDVUfWfRjKuwb4VgA2zEA timestamp: type: string format: RFC3339 description: Time the item occurred example: '2019-07-03T04:30:12.07Z' initiator: $ref: '#/paths/~1api~1v1~1tasks~1%7BtaskId%7D/get/responses/200/content/application~1json/schema/properties/createdBy' responder: $ref: '#/paths/~1api~1v1~1conversation-items/post/responses/200/content/application~1json/schema/properties/responder' content: title: Note description: '' type: object required: - type properties: type: type: string enum: - CONVERSATION_NOTE body: type: string description: text of the note example: Customer has requested more information about our loyalty program. attachments: type: array description: attachments to the message items: type: object properties: id: type: string description: ID of the attachment example: pOVVdzweSumI4bFxjlT8LA contentType: type: string description: Content type of the attachment example: image/png filename: type: string description: Filename of the attachment example: attachment-1.png fileSize: type: integer description: File size of the attachment in bytes example: 1024 '404': description: An item with the given id could not be found /api/v1/conversation-items/{itemId}/reply: post: tags: - Conversations summary: Reply to Message description: Sends a response to a conversation item. If no agent is assigned to the conversation, the conversation is assigned to the API User who made this call. operationId: replyToMessage parameters: - in: path name: itemId description: 'id of the conversation item ' schema: type: string example: pOVVdzweSumI4bFxjlT8LA required: true requestBody: content: application/json: schema: title: Message description: Message that can be sent in Gladly type: object required: - content properties: content: title: Message content oneOf: - title: Email Message Content description: The content of the email message type: object required: - type - body properties: type: type: string enum: - EMAIL body: type: string description: HTML message that can be added to an email example:

Customer service is being reinvented by Gladly

bodyPlain: type: string description: Plain text message that can be added to an email example: Customer service is being reinvented by Gladly - title: Chat Message Content oneOf: - title: Message Content description: The content of the chat message type: object required: - type - body properties: type: type: string enum: - CHAT_MESSAGE messageType: type: string enum: - TEXT body: type: string description: Plain text message example: Customer service is being reinvented by Gladly - title: QuickReply Request Content description: The content of chat QuickReply request type: object required: - type - body - messageType - messageData properties: type: type: string enum: - CHAT_MESSAGE messageType: type: string enum: - QUICK_REPLY_REQUEST body: type: string description: Plain text message example: What can I help you with? messageData: type: object description: QuickReply request data required: - options properties: options: type: array title: Options description: The options the user can choose from, the number of options must be greater or equal to one and less or equal to 10. items: type: object title: Option required: - id - label properties: id: type: string title: Id description: Id of this option, must be unique in the request and only contain alphanumeric characters (a-z, A-Z, 0-9), hyphen or underscore label: type: string title: Label description: Text label of the option that will be presented to the user (max length 50 characters) - title: Facebook Message Content description: The content of the facebook message type: object required: - type - body properties: type: type: string enum: - FACEBOOK_MESSAGE body: type: string description: Plain text message example: Customer service is being reinvented by Gladly - title: Instagram Direct Message Content description: The content of the Instagram Direct message type: object required: - type - body properties: type: type: string enum: - INSTAGRAM_DIRECT body: type: string description: Plain text message example: Customer service is being reinvented by Gladly - title: SMS Message Content description: The content of the sms message type: object required: - type - body properties: type: type: string enum: - SMS body: type: string description: Plain text message example: Customer service is being reinvented by Gladly - title: Twitter Direct Message Content (decommissioned as of 04/20/2023) description: The content of the twitter direct message type: object required: - type - body properties: type: type: string enum: - TWITTER body: type: string description: Plain text message example: Customer service is being reinvented by Gladly - title: WhatsApp Message Content description: The content of the WhatsApp message type: object required: - type - body properties: type: type: string enum: - WHATSAPP body: type: string description: Plain text message example: Customer service is being reinvented by Gladly examples: Reply with email: summary: Example of an email reply message value: content: type: EMAIL body: Hi!
Of course we can help with your issue! bodyPlain: "Hi!\n We can definitely help you with that!" Reply with chat message: summary: Example of a chat message reply message value: content: type: CHAT_MESSAGE messageType: TEXT body: Hi from chat! Reply with chat quick reply: summary: Example of a chat quick reply message value: content: type: CHAT_MESSAGE messageType: QUICK_REPLY_REQUEST body: Hi from chat! Please select an option! messageData: options: - id: option-1 label: option one - id: option-2 label: option two Reply with facebook message: summary: Example of a Facebook reply message value: content: type: FACEBOOK_MESSAGE body: Hi from Facebook Messenger! Reply with instagram direct message: summary: Example of an Instagram Direct reply message value: content: type: INSTAGRAM_DIRECT body: Hi from Instagram Direct! Reply with sms message: summary: Example of an SMS reply message value: content: type: SMS body: Hi from SMS! Reply with twitter direct message (decommissioned as of 04/20/2023): summary: Example of a Twitter reply message value: content: type: TWITTER body: Hi from Twitter Direct Messages! Reply with whatsapp message: summary: Example of a WhatsApp reply message value: content: type: WHATSAPP body: Hi from WhatsApp! responses: '201': description: The reply was created successfully. Note that creation doesn't guarantee delivery headers: Location: schema: description: Relative URL of the created message example: /api/v1/conversation-items/HVFDjpu1SCKJlDR7rRKkCQ '400': description: Invalid field(s) in request body content: application/json: schema: $ref: '#/components/schemas/Errors' examples: Closed conversation: summary: Error trying to act on closed conversation value: errors: - code: invalid detail: you cannot reply to items in closed conversations Empty type: summary: Error trying to send a message with an empty type value: errors: - code: blank attr: content.type Wrong type: summary: Error trying to send a reply message to unsupported type value: errors: - code: invalid detail: type [VOICEMAIL] is not supported Body too long: summary: Error trying to send a message with too long content value: errors: - code: too_long attr: content.body detail: content.body cannot be larger than 2048 characters Not a customer message: summary: Error trying to send reply to a message that was not from the customer value: errors: - code: invalid detail: you can only reply to customer messages '404': description: A conversation item with the given id could not be found /api/v1/conversation-items/{itemId}/redact: post: tags: - Conversations summary: Redact Conversation Item description: 'For supported items, the item''s content will be removed but the item will remain in the conversation timeline. Supported types are Chat Message, SMS Message, Email, Twitter (decommissioned as of 04/20/23, but can still be redacted), WhatsApp, Voicemail, Phone Call. ' operationId: redactContent parameters: - in: path name: itemId description: 'id of the conversation item ' schema: type: string example: pOVVdzweSumI4bFxjlT8LA required: true requestBody: content: application/json: schema: description: The request body should be empty responses: '201': description: The redaction was successful. headers: Location: schema: description: Relative URL of the redacted item example: /api/v1/conversation-items/HVFDjpu1SCKJlDR7rRKkCQ '404': description: A conversation item with the given id could not be found components: schemas: Errors: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' example: - attr: content code: blank detail: content cannot be blank NotFoundErrors: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' example: - code: not_exist detail: entity does not exist Error: type: object properties: attr: type: string description: Identifies the field causing the error code: type: string description: Code indicating the error type detail: type: string description: More details describing what went wrong securitySchemes: BasicAuth: type: http scheme: basic description: 'Gladly API uses token-based **Basic Authentication**. API tokens are associated with designated Gladly users. To create and use an API token, your user must have the API User permission. An API token can be used to perform any API request without restriction. | user name | password | | ----------- | --------- | | agent email | API token | The credentials must be passed via an `Authorization` HTTP header. All requests must be made over HTTPS. ```shell curl -u user@organization.com:$GLADLY_API_TOKEN \ https://organization.gladly.com/api/v1/organization ``` ' basicAuth: type: http scheme: basic description: HTTP Basic auth — username is the API user email; password is the API token. Requires the "API User" permission. x-tagGroups: - name: REST API tags: - Agents - Public Answer - Answer Management - Audiences - Business Hours - Communications - Conversations - Customers - Events - Export - Freeform Topics - Inboxes - Organization - Proactive Conversations - Reports - Tasks - Teams - User Identity - Topics - Webhooks - name: Webhooks tags: - Summary - Payloads - name: Lookup API tags: - Customer Lookup - name: Resources tags: - Versioning - Error Handling - Rate Limit - Rich Content - Launching Soon