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 |
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.
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. |
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
Name |
Required |
Description |
$Expression |
Yes |
The search expression filled in the the ROBIN Search by the agent |
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
Name |
Type |
Required |
Description |
customers |
Object |
Yes |
Customer specific contact details |
email_address |
String |
Yes |
E-mail from the customer which resembles the search expression |
name |
String |
Yes |
Name of the customer |
phone_number |
String |
Yes |
Phone number from the customer |
order_count |
String |
Yes |
Total amount of orders the customer has |
total_spent |
String |
Yes |
Total amount of money the customer has spent |
orders |
Object |
Yes |
Object which contains order details that resembles the search expression |
email_address |
String |
Yes |
The email address from the customer who filled in the order |
order_number |
String |
Yes |
Number from the order |
order_date |
String |
Yes |
Date that the order has been placed |
revenue |
String |
Yes |
Total amount of money that the order resembles |
name |
String |
Yes |
Name from the customer that has filled in the order |
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 |
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 |
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. |
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.
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. |
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 |
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 |
... |