UBI Command Examples:

ubicommands.markdown

UBI Command Fields

Any UBI command consists of the following fields. Some are required, others are optional.

1. name (required) - name of the the command in UBI.
2. short_description (required) - description of command when <commands> is executed.
3. error_message (required) - response UBI gives when command failed.
4. success_message (required) - response that gives when command is successful. must contain {} to be valid. {} is used as a string substution (i,e, "Your horoscope is {}", where {} will be replaced by the response of the API.
5. number_of_parameters (required) - the number of parameters (does not include API key) your function can accept. Currently 0 ("bloomberg") or 1 ("bible john316")
6. api_url (required) - the url of the API. Use string substitution to replace url
7. api_key_query_param (optional) query parameter used for API key (some APIs do not require this)
8. api_key (optional) api key (some APIs do not require this)
9. can_use_in_group_chat (not currently used)
10. active (if True, shows up in the list)
11. response_parse_instructions (required) response parse instructions, see below.

Response Parse Instructions:

The response parse instruction parameter is how you tell UBI how to parse your JSON output.

• If your API endpoint returns text only, just leave this parameter unset (nothing to parse)
• We do not support XML responses
• We do not support multiple embedded list support (yet)
• parameters are separated by period .
• [] tells ubi to return multiple response (see example 4, or any of the news API integrations)

Example 1

• JSON: { 'verse': 'this is the bible verse' }
• Parse Instruction: verse
• SMS Reponse: 'this is the bible verse'

Example 2

• JSON: [{ 'verse': 'this an embedded bible verse' }]
• Parse Instruction: 0.verse
• SMS Reponse: 'this an embedded bible verse'

Example 3

• JSON: This is a text response
• Parse Instruction: Leave the parameter null
• SMS Reponse: This is a text response

Example 4

• JSON: { 'articles' : [{ 'verse': 'v1' }, { 'verse': 'v2' }, { 'verse': 'v3' }, ]
• Parse Instruction: articles.[].verse
• SMS Reponse:

* v1 
* v2
* v3

Example Commands:

The following is a list of example API integrations

Example 1, Bible API integration

The following API key uses:

• 1 query parameter,
• no API key / auth is required

UBI Inputs

[Example API] (http://labs.bible.org/api/?passage=John%203:16&type=json)

• Name: bible1
• Short Description: bible1
• Error Message: Sorry, this API Failed
• Success Message: {}
• Number of Parameters: 1
• API URL: http://labs.bible.org/api/?passage={}&type=json
• API Query Parameter: Not set
• API Key: Not set
• Response parse instructions: 0.text

Example 2, Random Bible API integration

[Example API] (http://labs.bible.org/api/?passage=random)

The following API key uses:

• no API query parameter (provides random output)

• no API key / auth is required

• Name:

• Short Description: bible

• Error Message: Sorry, an error occurred. Please try again later.

• Success Message: {}

• Number of Parameters: 0

• API URL: http://labs.bible.org/api/?passage=random

• API Query Parameter: Not set

• API Key: Not set

• Response parse instructions: Not set

Example 3, techcrunch integration

[Example API] (https://newsapi.org/v1/articles?source=techcrunch&sortBy=top)

The following API key uses:

• one query parameter

• requires a valid API key

• accepts two different parameters: top or latest

• Name: techcrunch

• Short Description: techcrunch <top | latest>

• Error Message: Sorry, an error occurred.

• Success Message: {}

• Number of Parameters: 1

• API URL: https://newsapi.org/v1/articles?source=techcrunch&sortBy={}

• API Query apiKey

• API Key: xxxxxxxxx

• Response parse instructions: articles.[].title