Skip to main content

Configuring REST API

Chad Allard
  • Updated

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 the 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 response, custom URL parameters, and error codes.

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 with a JSON body to this endpoint, we return a calendar booking page (public availability) that you can place within your booking flow, as you desire. 

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": { . . . },
}'
You would replace the values in orange with the values from your Chili Piper instance. The router name can be found in the Inbound Router settings, and the domain name can be found at the beginning of all of your public booking links. 

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": true,
      "disableRelation": false,
      "skipOwnershipLogic": false,
      "webHook": "https://webhook.site/9asd292-292asd92-29asd2-2929asd",
      "locale": "en_US"
   },
   "utm": {
     "campaign": "my-campaign",
     "source": "concierge",
     "medium": "landing_page",
      "term": "booking",
      "content": "some_content"
   },
   "event": {
     "SF_field_API_name__c": "value",
      "some_other_field__c": "field_value"
   }
}

"event":{} is optional and will pass any details you provide through to the CRM event that is created upon booking for further reporting. Be sure that it sits separate from the options section, unlike how this is implemented in our JS snippet. 

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.

Passing custom UTM Parameters 

If you'd like to pass your UTM parameters through the booking flow into Chili Piper, you can add the following example parameters where they represent the different UTM values.

"utm": {
   "campaign":"my-great-campaign",
   "source":"socialmedia",
   "medium":"web",
   "term":"cost-per-click",
   "content":"chili-piper-link"
},

 

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 the response so that you can track each unique booking request if needed. 

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

NOTE: When are using live calls with Chili Piper, the reponse back with contain 'realTime'Url' when a user is available for a live, call. In this case, you'd want to use this URL instead to offer the live call option

{
   "routeId": "508b2f5f4a37500001ba7ffb",
   "url": "https://yourdomain.chilipiper.com/book/queuename/?id=0030W00003ufJY1QAM&routeId=508b2f5f4a37500001ba7ffb&marketing=true&locale=en_US",
"realtimeUrl": "https://yourdomain.chilipiper.com/book/kickoff-backup/?id=0036T000047DtQCQA0&routeId=6230c82ce4846956fa75244a&marketing=true&withPhone=true",

   "redirect": {
     "enabled": false,
     "closeStrategy": "Landing",
     "timeout": 5,
     "phoneCallRedirectEnabled": false,
     "redirectCallTimeoutStrategy": "AfterCallEnds",
     "redirectCallTimeout": 5
   }
}

 

 

Error Codes

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

8001 Can't find Default Booker for Inbound Router
8002 Salesforce API Error. Can't save prospect
8003 no rules match
8004 no queue uri could be found
8005 no owner link build When using an "ownership-based" algorithm

 

Webhook

If you would like to return data upon booking, rescheduling, reassignment, or cancellations, you must 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 the 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. 

 create When the booking is created.
 reschedule When the meeting has been rescheduled by the prospect or reschedule link.
 agent_reschedule When the rep moves the meeting manually via the calendar.
 reassign When the rep reassigns the meeting.
 cancel When the rep deletes the meeting from the calendar.
 prospect_cancel When the prospect uses a public cancel URL.

Upon a meeting getting rescheduled or canceled, 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:

marketing Boolean True / False (default False) Prevents form from being displayed to the customer. Note, you must provide lead information either via form option or ID. Also removes header of booking page + allows the use of title element. 
footer Boolean True / False (default True) Sets whether to show the booking page's footer.
title   Defines a custom title on the page itself (not to be confused with the browser title). Marketing=true is required for this to be displayed.
titleStyle   Font type and size and color hex, eg: Roboto 22px 2F2F2F
processRedirect   Redirect to this page when booked
closeRedirect   Redirect to this page when the "X" is clicked
hide_x Boolean True / False (default False) Hides the top-right X on the page
hide_title Boolean True / False (default False) Hides the title / thank you message on the page
redirectTimeout Int (seconds)

Determines the amount of time after a successful booking that the page is redirected to the location set via processRedirect 

example: redirectTimeout=3&processRedirect=https://www.google.com

would redirect to https://www.google.com after 3 seconds of the meeting being booked

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 web form, you can learn how to do this via Query string parameters for more information.

Javascript Messaging in Browser

For custom event messages sent to the browser, please refer to this article.

Javascript API

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

Related articles