Introduction

Welcome to the documentation site of the Mobile Service Cloud (Advanced & Pro) API.

In October 2020, CM.com acquired ROBIN - a leading conversational helpdesk system designed to help customer service teams deliver excellent customer service experiences in the most efficient way. Nowadays, the ROBIN helpdesk system is called ‘Agent Inbox’ as part of CM.com’s Mobile Service Cloud (Advanced & Pro).

Please note that the documentation refers to ‘ROBIN’ instead of Mobile Service Cloud.

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:

Timeframe Number of requests
Per second 3
Per minute 180
Per hour 10000
Per day 100000

Dynamic integration

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

Name Required Description
$EmailAddress Yes* The email address from the customer
$PhoneNumber Yes* The phone number from the customer

* 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

Name Type Required Description
name String Yes Returns the full name from the customer
email_address String Yes Returns the email address from the customer
phone_number String Yes Returns the phone number from the customer
customer_since String Yes Shows the date when the customer purchased his first order. Date format is: "YYYY-MM-DD"
total_spent String Yes Returns the total amount the customer has spend at the store(s)
order_count Float Yes Returns the total amount of orders the customer has at the store(s)
panel_view Object No A JSON object to put custom fields in to show more information about the customer
custom_field String No This variable is placed inside panel_view. You can rename the key and the value to anything you'd like -- as long as the value is returned in a string form

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

Name Required Description
$EmailAddress Yes The email address from the customer

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

Name Type Required Description
orders Array Yes The parent object to store all order_number objects in
order_number String Yes The number of the order which is also used as parameter for the Order details endpoint.
list_view Array Yes Inside list_View you can add custom fields to show information per order in the panel.
custom_field String No This variable is placed inside list_view. You can rename the key and the value to anything you'd like -- as long as the value is returned in a string form.

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

Name Required Description
$Id Yes The order_number of the clicked object of “orders” from Endpoint 2 “Order list”

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

Name Type Required Description
display_as String Yes The layout the information in showed in the panel (details, row and columns)
data Object Yes This is the object where all the information is stored.

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

Name Required Description
$Email Yes The email address from the customer

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

Name Type Required Description
email_address String Yes Email address from the customer
customer_since String Yes Date of the first order
order_count Integer Yes Total amount of orders the customer has
currency String Yes Default currency from the customer
total_revenue Float Yes Total amount of revenue the customer has brought in
last_order_date String Yes Date of the last order

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

Code Description
201 Created
400 Bad Request
401 Invalid authorisation data

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

Name Type Required Description
email_address String Yes Email address from the customer
customer_since String Yes Date of the first order
order_count Integer Yes Total amount of orders the customer has
currency String Yes Default currency from the customer
total_revenue Float Yes Total amount of revenue the customer has brought in
last_order_date String Yes Date of the last order

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

Code Description
201 Created
400 Bad Request
401 Invalid authorisation data

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

Name Type Required Description
order_number String Yes Ordernumber of the order, special field, needed to recognize an order number in a question asked by a customer
email_address String Yes Email address of the customer
revenue Float Yes Total amount of money that the order resembles
old_revenue Float No When updating the order, the previous "revenue" is placed here
profit Float No The total profit that is made with this order
old_profit Float No When updating the order, the previous "profit" is placed here
order_date String Yes Date that the order has been placed
is_first_order Boolean Yes When true the order counts as acquisition, when false the order counts as retention
webstore_url String No The URL of the webstore where the order is placed

Conversations

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

Code Description
200 OK
400 Bad Request
401 Invalid authorisation data

Request body


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

Request schema

Name Type Required Description
emailAddress String No Email address of the customer
orderNumber String No Number from the order
skip Integer No The number of conversations you want to skip
guid String No The generated GUID of the conversation.

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

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 converastion
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 emailadres 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

Custom panel

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.

Configuration

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

Name Required Description
$EmailAddress Yes* The email address from the customer
$PhoneNumber Yes* The phone number from the customer
$ExternalIdentifier Yes* An identifier from the customer that isn't an email address or phonenumber

* 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

Name Type Required Description
data Array Yes The parent object to store all custom panel objects in
id String Yes The id that is also used as parameter for the Custom panel details endpoint.
custom_field String No This variable you can rename the key and the value to anything you'd like -- as long as the value is returned in a string form.

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

Name Required Description
$Id Yes The order_number of the clicked object of “orders” from Endpoint 2 “Order list”

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

Name Type Required Description
display_as String Yes The layout the information in showed in the panel (details, row and columns)
data Object Yes This is the object where all the information is stored.

VoIP

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

Name Required Description
apikey Yes The apikey of your subscription

Response codes

Code Description
201 Created
400 Bad Request
401 Invalid authorisation data
406 Not acceptable

Request body


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

Request schema

Name Type Required Description
Id String Yes The unique identifier of the phone all from the VoIP provider
EventType String Yes Answered, Disconnected or Transfer
PhoneNumber Integer Yes Phone number in the international standard
PhoneExtension String Yes The extension number of the device which answers the phone call
Direction Float Yes Inbound or outbound
PhoneReferrer String No The phone number dialed by the customer (used to route the conversation to the correct webstore within ROBIN)

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.

Channel API

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

Code Description
201 Created
400 Bad Request
401 Invalid authorisation data

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

Name Type Required Description
ChannelAccountExternalIdentifier String Yes This is the registered name for the custom channel, determined when the channel is registered.
ConversationGuid String No The generated GUID of the conversation.
ConversationExternalIdentifier Integer Yes This is the external ID for the conversation.
MessageExternalIdentifier String Yes This is the external ID for the message.
RelationExternalIdentifier Float Yes TThe external ID for the relation (usually an email address or phone number)
RelationName String Yes The name for the relation
Content String Yes The content of the answer.
IsPrivate Boolean No Indicates whether the returned message is marked private by the agent.
Referrer String No The referrer for the message, e.g. an URL
Subject String No The subject for the message when a new conversation will be created.
SentDateTime String No The date when a message was sent.
Attachments String Yes An attachment object
FileName String Yes The filename of the attachment. Can be left empty if no attachments are attached.
Base64Content String No The bytes of the attachment as base64 encoded string. Can be left empty if no attachments are attached.

Presence

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

Name Required Description
apikey Yes The apikey of your subscription
channelName Yes The name of the channel (Email, Chat, WhatsApp, SMS, WebChat, Facebook Messenger, Instagram, Apple Business Chat and Twitter)
referrer No The referrer that are configured within a web store (URLs, e-mail addresses phonenumbers, bot variables)

Response codes

Code Description
200 OK
400 Bad Request
404 Not Found

Response body


							Online or Offline
						

Response schema

Name Description
Online At least one agent connected to the requested channel within the web store has an online status
Offline All agents connected to the requested channel within the web store have an offline status

Show customer

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

Code Description
201 Created
400 Bad Request
401 Invalid authorisation data

Request body


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

Request schema

Name Type Required Description
user_email_address String No Email address of the ROBIN agent that will receive the notification
customer Object Yes Customer to search. Contains an email address and a phone number. At least one of them must be provided
email_address String No Email address of the customer to lookup
phone_number String No Phone number of the customer to look up.
external_identifier String No ...