REST API for Routing Meetings Online

Chili Piper offers a server-to-server API endpoint for calling our booking workflow. This allows you to automate the display of a queue's calendar programmatically, or where use of our JS API / snippet is not appropriate. 

In this article, we will cover what request body parameters to send with this endpoint, how to utilize a webhook responses, custom URL parameters, and error codes.

• Request Description & Syntax
  • Language Localization Parameter in REST API
• Response
  • Error Codes
• Webhook
• URL Parameters
• Javascript Messaging in Browser
  • How to set up the Event Listeners
  • Action Messages
• Javascript API

Request Description & Syntax

We provide a server-to-server public endpoint that takes several booking parameters such as form fields, custom options, and CRM event data. No authentication is required.

POST: https://api.chilipiper.com/marketing/yourdomain

Upon submitting a successful POST to this endpoint, we return a calendar booking page (public availability) that you can place within your booking flow, as you desire. 

• Form fields: should contain correct Salesforce Lead format fields (case sensitive) https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_lead.htm
• Options for form (router name, locale, webhook, debug true false, etc) 
• Event options for custom fields for events in SFDC

Example curl format: 

curl --location --request POST 'https://api.chilipiper.com/marketing/yourdomain' \
--header 'Content-type: application/json' \
--data-raw '{
 "form": {
 "FirstName": "test",
 "LastName": "test",
 "Company": "CompanyTest",
 "Email": "chilitest@chilipiper.com"
 },
 "options": {
 "router": "inbound_router_name",
 "debug": false,
 "map": false,
 "webHook": "https://webhook.site/d0eadad5-426a-49ef-aba8-ebd0092cd854",
 "locale":"en_US"
 },
 "event": { . . . },
}'

More example form fields, options, and event parameters: 

{
  "form": {
    "FirstName": "TestFirst",
    "LastName": "TestLast",
    "Company": "Chili Piper",
    "Phone": "1234567890",
    "Email": "chilitest@chilipiper.com",
    "RecordTypeId": "01212000000VpBY",
    "LeadSource": "",
    "Status": "Open",
    "MailingCountry": "United States",
    "Country_Code__c": "ME",
    "Locale__c": "en_US"
  },
  "options": {
    "router": "inbound_router_name",
    "ownerId": "0056g00000ZGhrkAAC"
    "debug": false,
    "map": false,
    "disableRelation": false,
    "skipOwnershipLogic": false,
    "webHook": "https://webhook.site/9asd292-292asd92-29asd2-2929asd",
    "locale": "en_US"
  },
  "event": {
    "name": "Customer_Issue_Reason__c",
    "label": "Customer Issue Reason",
    "types": "picklist",
    "custom": true,
    "updateable": true,
    "nillable": true,
    "picklistValues": [
      {
        "value": "Account & Budget Management",
        "label": "Account & Budget Management",
        "active": true
      },
      {
        "value": "Ad Performance Concerns",
        "label": "Ad Performance Concerns",
        "active": true
      },
      {
        "value": "Advertising Account Administration",
        "label": "Advertising Account Administration",
        "active": true
      },
      {
        "value": "Billing",
        "label": "Billing",
        "active": true
      },
      {
        "value": "Campaign Features",
        "label": "Campaign Features",
        "active": true
      },
      {
        "value": "Cost, Budgeting & Bidding",
        "label": "Cost, Budgeting & Bidding",
        "active": true
      }
    ]
  }
}

"event":{} is optional and will pass any details you provide through to the CRM event that is created upon booking, for further reporting.

Language Localization Parameter in REST API

If you want to define the language that the presented booking page appears in, you can provide a “locale” option, to choose the language to be displayed in the online calendar (to translate the texts “What day is best for you?” and “what time works?”) 

"options": {
   "router": "inbound_router_name",
   "debug": false,
   "map": false,
   "locale": “fr_FR”
},

The values for the parameter “locale” should use the ISO 639-1 code; if a country is not supported, Chili Piper will default to English. Chili Piper has published our list of supported languages, updated from time to time.

Response

Our response returns the URL of the correct calendar based on the inbound concierge router you define. Your team then serves this URL to the user, in an iFrame embed or redirect or in another manner. 

We include a "routeId" on response so that you can track each unique booking request if needed. 

{
  "routeId": "508b2f5f4a37500001ba7ffb",
  "url": "https://yourdomain.chilipiper.com/book/queuename/?id=0030W00003ufJY1QAM&routeId=608b2f5f4a37500001ba7f7b&marketing=true&locale=en_US",
  "redirect": {
    "enabled": false,
    "closeStrategy": "Landing",
    "timeout": 5,
    "phoneCallRedirectEnabled": false,
    "redirectCallTimeoutStrategy": "AfterCallEnds",
    "redirectCallTimeout": 5
  }
}

Error Codes

In case of error, we’ll continue with the current error codes. 

Webhook

If you would like to return data upon booking, rescheduling, reassignment, or cancellations, you will need to use a webhook. We suggest that you pass the URL for the webhook in each request, that way you can change it at any time.

To define a webhook, add it to the POST request options as you can see in our example at the beginning of this article, or as follows:

"webHook”: "https://webhook.site/9asd292-292asd92-29asd2-2929asd"

The POST will be of the following format when a calendar action happens:

{
  "routeId": "608b31464a37500001ba7fbd",
  "eventId": "608b31626000850001c9a036",
  "actionType": "create",
  "assigneeId": "0050W0000076H5jQAE",
  "slot": {
    "start": 1619789400000,
    "end": 1619791200000
  }
}

eventId - is meeting's unique id in our database. Note this can be used when constructing reschedule or cancel URLs (see below).

actionType - We offer several actionType values depending on what happened to the meeting.
The only difference in the response in the example above would be the actionType field. 

Upon a meeting getting rescheduled or cancelled, etc, we'll hit the webhook saved for that event with the updated information. We will return a POST request with the adjusted actionType.

The reschedule link follows the following format:

https://yourdomain.chilipiper.com/book/reschedule?rescheduleId=eventId

The public cancel URL follows the following format:

https://yourdomain.chilipiper.com/book/cancel/eventId

Using the eventId returned by the webhook, you can construct either of those URLs and include them anywhere, including your CRM. Likewise, manual reschedules and deletions performed directly in the rep's calendar are also captured.

URL Parameters

You can pass specific URL parameters to modify the appearance, control, and redirects of the calendar window. This is extremely useful when calling the calendar via REST API.

Example:

https://organization.chilipiper.com/book/me/james-bond?id=prospect@email.com&marketing=true&title=Hey!URLParams&processRedirect=www.chilipiper.com&closeRedirect=www.chilipiper.com&redirectTimeout=3

Parameters:

We also offer several other parameters on personal booking links, queue links, and router links.

See Smart Booking Links for more information.

If you are looking to pre-fill your prospect's info into your webform, you can learn how to do this via Query string parameters for more information.

Javascript Messaging in Browser

Our JS client code broadcasts custom events to your browser when Chili Piper is loaded within a page. These messages can be captured via event listener or used with analytics apps to track when these actions occur.

How to set up the Event Listeners

This example is for illustrative purposes only, as you would likely want to capture this event data in some other useful way rather than presenting it to the console log. Note that the data is presented in JSON format.

<script>
window.addEventListener("message", receiveMessage, false);
function receiveMessage(event) {
 console.log("event.data " + JSON.stringify(event.data))}
</script>

In the above example, this would output something like this to web Console depending on the message / event (see below supported events).

event.data {"action":"availability-loaded"}

Action Messages

The following is a list of currently supported actions that we will send messages for, and where they will appear in the workflow.

Example of "booked" event:

{
   routeId: "5a7c654a2b52873a2ce5df57"
}

Example of "booking-confirmed" event:

{
   "routeId": "5a7c654a2b52873a2ce5df57",
   "eventId": "5b2124533a906b5f0bff32ad",
   "assigneeId": "00D1N000001S8LUUA0",
   "slot": {
      "start": 1536355315,
      "end": 1536356315
   }
}

Note: If the prospect closes the window before the second message is passed, you will not get the event data, but it could be retrieved with the routeId when a webhook is implemented

This cannot be used for reassignments as they are not done with an online calendar. Instead, we would capture these with a webhook as well. 

Javascript API

If you're simply looking to call Chili Piper from your client-to-server JavaScript code for full control of the workflow, see Concierge Snippet and API