Authentication

If you want access for the ROBIN API, please contact our support team. They will grant you access by providing you with the right combination of APIkey and API Secret. If you are setting up a dynamic integration, you will find an explanation about how to access the API here.

Limits

Because we have to make sure our system does not get overloaded by API calls, The ROBIN API works with request limits. As soon as you make a request (a request can be all verbs GET, POST, PUT, DELETE etc the API supports). The current limits are:

Introduction

In the settings of ROBIN it's possible to configure the endpoints with headers and also get the authentication (API key and API secret) for the POST requests. Go to the Settings > Integrations > Dynamic API and hit the "Add"-button. Now you can configure the integration according to your wishes.

Customer information

This endpoint has been designed to showcase the details of the customer. This endpoint gives the customer service rep a general overview of who the person is and his history with the company.

GET https://demo.com/customers?<yourEmailParameter>=$EmailAddress&<yourPhoneParameter>=$PhoneNumber
						

Parameters

* at least one of the two parameters need to be configured.

Response body

{
    "email_address": "email@address.com",
    "customer_since": "2014-01-28",
    "order_count": 12,
    "total_spent": "$154.95",
    "name": "John Doe",
    "phone_number": "+31612345678",
    "panel_view": {
        "custom_field1": "Value 1",
        "custom_field2": "Value 2"
    }
}							
						

Response schema

Orders list

The Order list endpoint shows the general points of the order in the Customer panel.

GET https://demo.com/orders?<yourEmailParameter>=$EmailAddress
						

Parameters

Response body

{
    "orders":
    [
        {
            "order_number": "RHQO1234",
            "list_view": {
                "order_number": "RHQO1234",
                "date": "29-01-2014 12:34",
                "status": "In progress"
            }
        }
    ]
}							
						

Response body when customer has no order

{
    "orders":
    []
}							
						

Response schema

Order details

The “Order details” endpoint shows the details of one order so the ROBIN Agent can see more information of one particular order from the customer. Once a ROBIN Agent clicks on order shown in the “Order list” from Endpoint 2, Endpoint 3 will be called by the parameter “ID” filled with the order_number in the object of “orders” from Endpoint 2 “Order list”.

GET https://demo.com/orders?<yourOrderNumber>=$Id
						

Parameters

Response body

{
  "details_view": [
    {
      "display_as": "details",
      "data": {
        "date": "29-01-2014 12:34",
        "status": "In progress",
        "payment_status": "Partially paid",
        "shipment_status": "Partially shipped"
      }
    },
    {
      "display_as": "columns",
      "caption": "products",
      "data": [
        {
          "product": "Phone",
          "quantity": "1",
          "price": "$695.50"
        },
        {
          "product": "Tablet",
          "quantity": "2",
          "price": "$898.00"
        },
        {
          "product": "Shipment",
          "quantity": "",
          "price": "$10.00"
        },
        {
          "product": "Total",
          "quantity": "",
          "price": "$1603.50"
        }
      ]
    },
    {
      "display_as": "rows",
      "caption": "invoices",
      "data": [
        {
          "shipment": "<a href='http://shop.com/invoice/RHQI01'>RHQI01</a>",
          "status": "Paid",
          "amount": "$1200.00"
        },
        {
          "shipment": "<a href='http://shop.com/invoice/RHQI02'>RHQI02</a>",
          "status": "Not paid",
          "amount": "$403.50"
        }
      ]
    }
  ]
}						
						

Response schema

Search

The “Search” endpoint shows results of the search expression so that the ROBIN Agent can see all known orders, customers and conversations relating to the search keyword.

GET https://demo.com/search?<yourExpression>=$Expression
						

Parameters

Response body

{
    "customers": 
    [
        {
            "email_address": "email@address.com",
            "name": "Fullname",
            "phone_number": "+31612345678",
            "order_count": "1",
            "total_spent": "€123,45"
        }
    ],
    "orders": 
    [
        {
            "email_address": "email@address.com",
            "order_number": "RHQ1234",
            "order_date": "2017-01-12T12:34:56Z",
            "revenue": "€12,34",
            "name": "Fullname"
        }
    ]
}							
						

Response body with no results

If there is no customer or an order for the expression, make sure you response with the an empty array for customers and/or orders.

{
    "customers": 
    [],
    "orders": 
    []
}							
						

Response schema

Customer lifetime

The “Customer Lifetime” endpoint shows the total amount of orders and the total amount of revenue per customer.

GET https://demo.com/search?<yourEmailParameter>=$Email
						

Parameters

Response body

{
    "email_address": "email@address.com",
    "customer_since": "2017-01-12T12:34:56Z",
    "order_count": 12,
    "currency": "$",
    "total_revenue": 154.95,
    "last_order_date": "2017-04-05T12:34:56Z"
}							
						

Response schema

Customer POST

The “Customer Lifetime” endpoint shows the total amount of orders and the total amount of revenue per customer for every new conversation. But for older conversation you'll need the POST to update this information.

POST https://api.robinhq.com/dynamic/customers/
						

Response codes

Request body

{
  "customers": [
    {
      "email_address": "email@address.com",
      "customer_since": "2017-01-29T12:34:56Z",
      "order_count": 12,
      "total_revenue": 123.45,
      "currency": "$",
      "last_order_date": "2017-04-05T12:34:56Z"
    }
  ]
}						
						

Request schema

Order POST

The Orders POST lets ROBIN know that the customer has purchased an order, generates a win messages and fills in the right sales numbers. You can also update the order information, but therefor use the same order_number of the first POST

POST https://api.robinhq.com/dynamic/orders/
						

Response codes

Request body

{
  "orders": [
    {
      "order_number": "O1243",
      "email_address": "email@address.com",
      "revenue": 113.34,
      "old_revenue": 112.34,
      "profit": 13.34,
      "old_profit": 12.34,
      "order_date": "2017-04-05T12:34:56Z",
      "is_first_order": true,
      "webstore_url": "https://www.yourwebstore.com/"
    }
  ]
}						
						

Request schema

Introduction

The ROBIN API offers the possibility to retrieve conversations from the ROBIN 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.

Conversations

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

Response codes

Request body

{
  "emailAddress": "john@email.com",
  "orderNumber": "RHQO1234",
  "skip": 20,
  "guid": "2eeb7f72-0239-4104-9d85-d2300d214ff2"
}						
						

Request schema

Response body

{
  "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://robinhq.com",
      "startDateTime": "2015-07-08T15:39:04",
      "messages": [
        {
          "sentDateTime": "2015-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

Introduction

When a conversation is opened in ROBIN, the right-side panel can contain relevant information to that conversation and/or the customer. The profile can show personal customer details, as well as the orders that are associated with this customer, but also a conversation history for all channels. The API also offers the possibility to add a ‘custom’ panel to the profile. This custom panel can contain anything other entities such as orders from a separate retail POS system, repairs, newsletters, reviews, forum posts, tickets from a third party ticking system and more.

There also is the possibility to implement multiple custom panels and assign them to different Web Stores.

A custom panel needs to be configured in ROBIN and can be found in the settings in the integration section. To implement a custom panel the following data is required for a custom panel:

• The name of the panel (e.i. the caption that is to be displayed in the main panel)
• The name of the details view
• The URL for retrieving data
• The URL for retrieving details
• Headers to be submitted to both URLs
• An icon to be displayed in the main panel (size 18*21)
• An icon to be displayed in the navigation area (size 26*52 black and white version. This is for the hover effect)

Custom panel list

The Custom panel list endpoint should return an object containing items that are to be displayed. The main panel will only show 3 items, when navigating to all items, the remaining will also be displayed.

GET https://demo.com/customerpanellist?<yourEmailParameter>=$EmailAddress&?<yourPhoneParameter>=$PhoneNumber&?<yourExternalIdentifierParameter>=$ExternalIdentifier
						

Parameters

* at least one of the three parameters need to be configured.

Response body

{
    "data":
    [
        {
            "id":"1",
            "description":"record 1",
            "field1":"this is field 1",
            "field2":"this is field 2"
        },
        {
            "id":"2",
            "description":"record 2",
            "field3":"this is field 3",
            "field4":"this is field 4"
        },
        {
            "id":"3",
            "description":"record 3",
            "field5":"this is field 5"
        },
        {
            "id":"4",
            "description":"record 4",
            "field6":"this is field 6"
        }
    ]
}						
						

Response schema

Custom panel details

When navigating to a specific item, the Custom panel details endpoint is invoked. This URL has one parameter: $id. This parameter is substituted with the id property if the item that is navigated to, and can be any string necessary to identify the item. The expected return string is an object with one property: “data”.

GET https://demo.com/custompaneldetails?<yourOrderNumber>=$Id
						

Parameters

Response body

{
  "details_view": [
    {
      "display_as": "details",
      "data": {
        "date": "29-01-2014 12:34",
        "status": "In progress",
        "payment_status": "Partially paid",
        "shipment_status": "Partially shipped"
      }
    },
    {
      "display_as": "columns",
      "caption": "products",
      "data": [
        {
          "product": "Phone",
          "quantity": "1",
          "price": "$695.50"
        },
        {
          "product": "Tablet",
          "quantity": "2",
          "price": "$898.00"
        },
        {
          "product": "Shipment",
          "quantity": "",
          "price": "$10.00"
        },
        {
          "product": "Total",
          "quantity": "",
          "price": "$1603.50"
        }
      ]
    },
    {
      "display_as": "rows",
      "caption": "invoices",
      "data": [
        {
          "shipment": "<a href='http://shop.com/invoice/RHQI01'>RHQI01</a>",
          "status": "Paid",
          "amount": "$1200.00"
        },
        {
          "shipment": "<a href='http://shop.com/invoice/RHQI02'>RHQI02</a>",
          "status": "Not paid",
          "amount": "$403.50"
        }
      ]
    }
  ]
}						
						

Response schema

Introduction

With ROBIN you can integrate with a phone provider. The integration improves the agent experience and enriches the helpdesk system with phone calls to create a mor complete view of the customer and enhance reporting data.

This integration leaves all the intelligence (IVR, queueing, routing, etc.) with the telephony system. It only connects the telephony system to ROBIN. It does this by connecting a user in ROBIN (an agent) to a phone extension number (a piece of software on a mobile phone or a physical phone on a desk).

• When a phone call comes in, and the agent answers the call, ROBIN automatically opens the ‘conversation view’
• When ROBIN recognizes the phone number (needs CRM/eCommerce data connection), we automatically (dynamically) retrieve relevant customer/order data and fill the Customer Profile
• When we don’t recognize the phone number (for instance because the customer didn’t fill in the phone number when ordering), the Customer Profile stays empty
• The agent can then ask for e-mail address, fill it into the Customer Profile, and then the profile automatically fills with the right data
• In case ROBIN finds more than one customer with this phone number, this phone number is placed in the search field on the dashboard and the search results are shown
• ROBIN automatically logs 1) when the call comes in, 2) who answered it, 3) if it’s transferred to someone else, 4) and when the call is ended
• This way your phone data becomes part of the ROBIN reporting suite, so the customer has unified reporting data
• The agent can also easily log additional notes in the phone call conversation and or collaborate with a colleague
• In addition, the logged phone calls become part of the customer’s conversation history.

Register event

POST https://api.robinhq.com/voip/registerevent/<apikey>
						

Parameters

Response codes

Request body

{
    "Id": "24c562241e9f",
    "EventType": "Answered",
    "PhoneNumber": "+31612345678",
    "PhoneExtension": "201",
    "Direction": "Inbound",
    "PhoneReferrer": "+31858770023"
}
						

Request schema

Native connectors

We have off-the-shelf integrations for VoIP providers. Please contact our support team to help you with setting up the integration for Xelion, Voys/VoIPGRID, Mondago and 3CX.

Introduction

In ROBIN there is a possibility to use your own custom channel. In order for this to work, the ROBIN API needs to be configured (please contact support@robinhq.com for assistance). A custom channel has the following characteristics that needs to be defined before getting started:

External identifier
Name
Avatar (2 sizes: 18\18px and 26\26 px)
Webhook URL
Support private messaging (true/false)
Send private as email (true/false)
Support select webstore (true/false)
Support sending attachments

The incoming and outgoing requests are the same for a custom channel, but there is one thing that we want to highlight: ConversationGuid. This field is generated by ROBIN. So for the first incoming request, this doesn't has any value or function. With the first answer the agent from ROBIN we will send the ConversationGuid in the outgoing JSON. If the next incoming request has the same ConversationGuid, we will map the message into that conversation without having matching external identifiers for Conversation and Relation.

Messages

POST https://api.robinhq.com/messages/
						

Response codes

Request body

{
  "ChannelAccountExternalIdentifier": "customChannel",
  "ConversationGuid": "robinConvGuid",
  "ConversationExternalIdentifier": "convId",
  "MessageExternalIdentifier": "messId",
  "RelationExternalIdentifier": "john@email.com",
  "RelationName": "John",
  "Content": "This is a message",
  "IsPrivate": false,
  "Referrer": "http://robinhq.com",
  "Subject": "Question",
  "SentDateTime": "2017-09-12T12:34:56",
  "Attachments": [
    {
      "FileName": "attachment.txt",
      "Base64Content": "MQ=="
    }
  ]
}
						

Request schema

Introduction

Within' a ROBIN subscription, there are two ways to treat a conversation: instant (meaning 'live' or 'real-time') and non-instant (a custom SLA of anywhere between 1 minute and e.g. a couple of days). In order to answer conversations in real-time you need to offer real-time availability. We call this 'presence'. With this end-point you can check presence for a specific channel within' your ROBIN subscription. When you define a referrer, you can then also check presence for a specific web store.

Presence Check

GET https://presence.robinhq.com/api/v1?apikey=<apikey>&Channel=<channelName>&referrer=<referrer>
						

Parameters

Response codes

Response body

							Online or Offline
						

Response schema

Introduction

The ShowCustomer feature is made for use in brick stores in combination with a POS system. When the customer card is scanned, the POS system will send a POST to ROBIN which will open a conversation.

Show customer

POST https://api.robinhq.com/showcustomer
						

Response codes

Request body

{
  "user_email_address": "user@robinhq.com",
  "customer": {
    "email_address": "customer@shop.com",
    "phone_number": "+31612345678",
    "external_identifier": "customer_1234"
  }
}			
						

Request schema

Introduction

Fill your CDP with data from ROBIN! For the CDP configuration, please contact support. They will help you setup the CDP and configure the right headers and webhooks. When the configuration is done, the requests will be delivered to that webhook with the following JSON body:

CDP Payload

Response body

{
  "Name": "ConversationTagsUpdated",
  "Payload": {
    "Tags": "Tag 1, Tag 2",
    "ChannelName": "Chat",
    "Subject": "Question",
    "WebStore": "Web store",
    "EventUtcDateTime": "2022-06-13T10:23:36.667",
    "AgentName": "Petra",
    "ConversationId": "28ba3e2a-55e6-ec11-9973-8038fb72f8ed",
    "SubscriptionId": 16,
    "RelationId": "db59a603-4857-ec11-9942-8038fb72f8ed",
    "RelationName": "John Doe",
    "EmailAddress": "JohnDoe@robinhq.com",
    "PhoneNumber": "+316 202 56 328"
  }
}
						

Request schema