Prologue

We are assuming that you have already created a ConvBot and created at least one Gambit in it. If you haven’t, then check out the getting started guide and come back here. You can check out what a Gambit means here.

Configure API in a Gambit

Open a gambit in your ConvBot. At the very top on the gambit modal you should see a checkbox saying API-Config, go ahead and check that box. You will see a new section slide open. Something like this:

API-Config section in a Gambit

Here you can do all the settings of API call. You can set:

  • HTTP Request method (GET, POST, PUT, etc..)
  • The URL endpoint to make the request
  • Set any header fields that you want to put in the Request. This is useful if you want to pass some API Key or Authorization token or set custom content-type etc..
  • Set the data that you want to pass in the API call. This data can be:
    • x-www-form-urlencoded (default), which will be a list of key value pairs that you can add in the input fields right below it.
    • raw, which can be JSON, XML or text and you can select this from the drop-down menu next to it. You can put the corresponding data in the textarea below it.

That’s it, click on that SEND button next to the URL and see the results in a nice format right below. Check it out:

API Config results in Gambit

You can now save your gambit by clicking on the Green SAVE button on top.

Refer to Data in a Gambit

You must be asking. That’s all good, but how do I refer to this data that I have gotten from the API call and more importantly, how do I use the data given by the user somewhere else.

This is very simple. You can display all this data anywhere – in the message bubbles, in the options buttons etc. by referring to Gambit’s varid, between double braces. e.g.

{{ursp.giphy_search_query}}

Gamit’s varid is what you see at the very top of a gambit modal. Check the image – it is giphy_search_query in this case:

“giphy_search_query” is the varid of this Gambit

and you can put this anywhere:

  • in the message bubble text.
    • e.g. “You searched for {{ursp.giphy_search_query}} and I am now going to get it”
  • in Input UI section
    • in button options textarea
    • in redirect URL input field
  • in API-Config section
    • in the URL input
      • e.g. http://api.giphy.com/v1/gifs/search?api_key=dc6zaTOxFJmzC&q={{ursp.giphy_search_query}}
    • in the Header input fields
    • in the Data input fields and raw text area

Data input for API config in a Gambit

Data Scope

URSP:

ursp in {{ursp.giphy_search_query}} means it is the user response for that gambit. So {{ursp.giphy_search_query}} means replacing this value with the user response in a gambit, whose varid is giphy_search_query. So in this gambit, you have asked the user to give a search term to look for a gif and he gave Cats in pajamas, then this:

You searched for {{ursp.giphy_search_query}} and I am now going to get it
will become
You searched for Cats in pajamas and I am now going to get it

PRE:

Similarly you can access the API response data in a gambit using pre as in {{pre.giphy_search_results}}. So all that sweet data that came over the API call is accessible using {{pre.giphy_search_results}}. Gambit’s varid in this case is giphy_search_results

API Config Results JSON Data

Now look closely in this screenshot and you can access the data elements like gif type, id, URL, size, and source_post_url using following:

{{pre.giphy_search_results.data[0].type}}
{{pre.giphy_search_results.data[0].id}}
{{pre.giphy_search_results.data[0].images.fixed_height.url}}
{{pre.giphy_search_results.data[0].images.fixed_height.size}}
{{pre.giphy_search_results.data[0].source_post_url}}

Put these anywhere – in the message bubbles, in the button options, even in the API Config of some later Gambit.
Just use the standard JSON notation i.e. DOT (.) for Object property and Square Brackets ([0], [1], [2] etc..) for array element to refer to data in the JSON.

Tip: ursp and pre are all lowercase
Tip: Avoid putting any spaces in gambit varids. So use gambit_search_query, instead of gambit search query.

That’s it. Have fun playing with the API Feature, and let us know if you have any questions. You can drop us a mail at :
vinit@hellotars.com

Thank you.

 

 

 

How API Calls in a Gambit work

As you already know, a Gambit means one single messaging back and forth between the bot and user. The API Call is configured on a per gambit basis. That means you can configure the bot to call an API in one or more gambits throughout the ConvBot.

When an API Call is configured for a gambit, it makes an HTTP Request (GET, POST, PUT etc..) just before the bot displays the message bubbles of that gambit to the user. That means if you want to display some dynamic information in the current gambit, you should configure the API either in the current gambit, or any of the previous gambits that the user must have visited earlier in the conversation.