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 of the customer
$PhoneNumber Yes* The phone number of 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 of the customer
email_address String Yes Returns the email address of the customer
phone_number String Yes Returns the phone number of 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 of 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./td>
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 of 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 of 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 of 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 of 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 of 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 of 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 of the customer
$PhoneNumber Yes* The phone number of the customer
$ExternalIdentifier Yes* An identifier of 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 of 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 of the conversation
MessageExternalIdentifier String Yes This is the external ID of the message
RelationExternalIdentifier Float Yes TThe external ID of the relation (usually an email address or phone number)
RelationName String Yes The name of 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 of the message, e.g. an URL
Subject String No The subject of 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 ...

CDP

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

Name Type Description
Name String The name of the event: ConversationStarted, ConversationArchived and ConversationUpdated
Payload Object This is the data of the event
Tags String The tags attached to the conversation
ChannelName String The channel of the conversation
Subject String The subject of the conversation
WebStore String The web store of the conversation
EventUtcDateTime String The date and time when the event in UTC
AgentName String The name of the owner in the conversation
ConversationId String The generated ID of the conversation
SubscriptionId Integer The ID of the subscription within the ROBIN platform
RelationId String The generated ID of the customer
RelationName String The name from of customer
EmailAddress String The email address of the customer
PhoneNumber String The phone number of the customer