# Conversations Retrieval

# Introduction

The <<glossary:Agent Inbox>> API offers the possibility to retrieve conversations from the <<glossary:Agent Inbox>> helpdesk system. With the conversation endpoint you can show it in your CRM or backoffice. When you implement this and combine it with the dynamic integration, you'll have a two way integration where you can provide the right information at the right moment.

# Request for Conversations

`POST https://api.robinhq.com/conversations`

## Response codes

| Code | Description                |
| :--- | :------------------------- |
| 200  | OK                         |
| 400  | Bad Request                |
| 401  | Invalid authorisation data |

## Request body

```json
{
  "emailAddress": "john@example.com",
  "orderNumber": "CMO1234",
  "skip": 20,
  "guid": "2eeb7f72-0239-4104-9d85-d2300d214ff2",
  "conversationId": "28ba3e2a-55e6-ec11-9973-8038fb72f8ed"
}						
```

## Request schema

| Name           | Type    | Required | Description                                  |
| :------------- | :------ | :------- | :------------------------------------------- |
| emailAddress   | String  | No       | Email address of the customer                |
| orderNumber    | String  | No       | Number of the order                          |
| skip           | Integer | No       | The number of conversations you want to skip |
| guid           | String  | No       | The generated GUID of the conversation       |
| conversationId | String  | No       | The generated ID of the conversation         |

# Response for Conversations

## Response body

```json
{
  "conversations": [
    {
      "guid": "400a5018-0bee-44a4-fe5e-14d431134de5",
      "subject": "This is the conversation subject",
      "channel": "Chat",
      "state": "Open",
      "owner": {
        "type": "User",
        "name": "Petra",
        "emailAddress": "petra@email.com"
      },
      "webStore": "Default webstore",
      "category": "Question",
      "linkedOrderNumbers": "#1234,#4356",
      "tags": "Tag1, Tag2",
      "referrer": "http://cm.com",
      "startDateTime": "2021-07-08T15:39:04",
      "messages": [
        {
          "sentDateTime": "2021-07-08T15:39:04",
          "sender": {
            "type": "Relation",
            "name": "Nick",
            "emailAddress": "nick@mail.com"
          },
          "content": "I don't know what my apikey is, can you help me?",
          "scope": "External",
          "rating": "None"
        }
      ]
    }
  ]
}
```

## Response schema

| Name               | Type   | Required | Description                                                        |
| :----------------- | :----- | :------- | :----------------------------------------------------------------- |
| conversations      | Array  | No       | The parent object to store all conversations in                    |
| guid               | String | No       | The GUID of the conversation                                       |
| subject            | String | No       | The subject of the conversation                                    |
| channel            | String | No       | The channels of the conversation                                   |
| state              | String | No       | The state of the conversation (open, archived, snoozed and hidden) |
| owner              | Object | No       | Information about the agent who has ownership of the conversation  |
| type               | String | No       | The role of the owner in the conversation                          |
| name               | String | No       | The name of the owner in the conversation                          |
| webStore           | String | No       | The web store of the conversation                                  |
| category           | String | No       | The category of the conversation                                   |
| linkedOrderNumbers | String | No       | The linked orders of the conversation                              |
| tags               | String | No       | The tags attached to the conversation                              |
| referrer           | String | No       | The referrer/start position of the conversation                    |
| startDateTime      | String | No       | The date and time of the start of the conversation                 |
| messages           | Array  | No       | The parent object to store all messages in of the conversation     |
| sentDateTime       | String | No       | The date and time when the message was send                        |
| sender             | Object | No       | Information about the sender of the message                        |
| type               | String | No       | The role of the sender of the message                              |
| name               | String | No       | The name of the sender of the message                              |
| emailAddress       | String | No       | The email address of the sender of the message                     |
| content            | String | No       | The content of the message                                         |
| scope              | String | No       | The scope (external or internal) of the message                    |
| rating             | String | No       | The given rating for the message                                   |