Add-on Submission Guide
The following guide serves to help you through the Publisher Onboarding process.
The following section includes tips and examples to help you through the Technical Submission Form. Please be sure to also read through the Add-on API Requirements for details on the technical requirements.
The HttpBin Example Add-on:
The examples listed below outline an Add-on submission for the HttpBin API (see httpbin.org). HttpBin is a free service that echoes data in your http request back to you. If you were to build an Add-on for HttpBin, you would get back the Add-on data that Twilio sends in its request. Use the HttpBin examples below to understand the different ways to pass parameters to your API.
Please provide a brief description of your Add-on so we can understand what it does.
HttpBin echoes data in your HTTP request back to you.
Please be as specific as possible providing page numbers and section names for your specific API so that we can quickly understand the technical details.
Filling out this question correctly is absolutely critical so that we can test your API and validate it is compatible with our Marketplace interface. Below are examples for how we'd like you to define the mapping of our template parameters to invoke your API.
Querystring Parameters via GET
_10GET_10https://httpbin.org/get?apikey=YOUR_API_KEY&phone_number={{primary_address}}
JSON Dictionary via POST
In the example below, hardcoded_param=STATIC_VALUE will be sent exactly as-is for all requests and is not seen by the customer.
_10POST_10https://httpbin.org/post?hardcoded_param=STATIC_VALUE_10JSON Body_10{_10 "e164": "{{primary_address}}"_10 "message": "{{body}}"_10}
www-form-encoded via POST
_10POST_10https://httpbin.org/post?hardcoded_param=STATIC_VALUE_10_10www-form-encoded Body_10key1={{primary_address}}_10key2={{secondary_address}}_10key3={{body}}_10hardcoded_key=STATIC_VALUE
HTTP Headers via GET/POST
_10GET_10https://httpbin.org/get?hardcoded_param=STATIC_VALUE_10_10Headers_10key1={{primary_address}}_10key2={{secondary_address}}_10hardcoded_key=STATIC_VALUE
Vendor-defined Lookup parameters via GET/POST
Currently, only Lookup supports request-time parameters. If you are submitting a Lookup Add-on and would like to define custom parameters please do so by indicating your custom field value in double curly braces, {{ like in the example below. See our REST API: Lookups docs on how our API users will be passing the parameter.
Note: Support for vendor-defined parameters across other integrations will be available in the Console soon. When that is released, this guide will be updated accordingly.
_10GET_10https://httpbin.org/get?apikey=YOUR_API_KEY&phone_number={{primary_address}}&custom_param={{vendor_defined_field}}
Define a JSON schema to validate a request prior to invoking your API. The following schema limits phone numbers with +91 or +1 prefixes only. See Add-on Publisher Guide. This is optional.
_13{_13 "$schema": "http://json-schema.org/draft-04/schema#",_13 "type": "object",_13 "properties": {_13 "primary_address": {_13 "type": "string",_13 "pattern": "^\\+(91|1)[0-9]*$"_13 }_13 },_13 "required": [_13 "primary_address"_13 ]_13}
Define a JSON schema to validate a response before billing the end-user. The following schema ensures the response always contains the args.e164 parameter. See Add-on Publisher Guide. This is optional.
_20{_20 "$schema": "http://json-schema.org/draft-04/schema#",_20 "type": "object",_20 "properties": {_20 "args": {_20 "type": "object",_20 "properties": {_20 "e164": {_20 "type": "string"_20 }_20 },_20 "required": [_20 "e164"_20 ]_20 }_20 },_20 "required": [_20 "args"_20 ]_20}
Define a JSON path to clean an element from your response. See JSONPath Online Evaluator to test your JSON path. Also see Add-on Publisher Guide for more details. This is optional.
Result Cleaning Path:
By defining the two JSON paths below we are removing the origin and headers.Cookie elements from our HttpBin JSON body before it is wrapped in our response and passed to the user.
_10$.origin_10$.headers.Cookie
JSON response before:
_17{_17 "args": {_17 "apikey": "YOUR_API_KEY",_17 "phone_number": "{{primary_address}}"_17 },_17 "headers": {_17 "Accept": "*/*",_17 "Accept-Encoding": "gzip, deflate, sdch, br",_17 "Accept-Language": "en-US,en;q=0.8",_17 "Cache-Control": "no-cache",_17 "Cookie": "_cookie=monster",_17 "Host": "httpbin.org",_17 "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36"_17 },_17 "origin": "127.0.0.1",_17 "url": "https://httpbin.org/get?apikey=YOUR_API_KEY&phone_number={{primary_address}}"_17}
JSON response after:
_16{_16 "args": {_16 "apikey": "YOUR_API_KEY",_16 "phone_number": "{{primary_address}}"_16 },_16 "headers": {_16 "Accept": "*/*",_16 "Accept-Encoding": "gzip, deflate, sdch, br",_16 "Accept-Language": "en-US,en;q=0.8",_16 "Cache-Control": "no-cache",_16 "Host": "httpbin.org",_16 "Postman-Token": "60abdc13-1c06-5233-b6dc-00ba98f22070",_16 "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36"_16 },_16 "url": "https://httpbin.org/get?apikey=YOUR_API_KEY&phone_number={{primary_address}}"_16}
We support the following authentication schemes to access your API. Please use one of the examples below as a guide to how we'd like you to submit your credentials. Also take a look at our Default HTTP Headers to understand what we will be sending in our HTTP request.
Querystring via GET
_10https://httpbin.org/get?key=YOUR_API_KEY
Request Body via POST
_10https://httpbin.org/post_10_10www-form-encoded Body_10username=TWILIOPROD_10password=PASSWORD
HTTP Headers (Basic, Bearer) via GET/POST
_10Basic/Bearer Auth_10https://httpbin.org/get_10Username: TWILIOPROD_10Password: PASSWORD_10OR_10Bearer Token: BEARER_TOKEN
Description and examples of the different pricing models available are listed below:
- Single Price: Regardless of volume usage, customer will be charged a flat unit rate
- Example: $.0080/unit
- Tiered Pricing: For customers who will reach volume scale, offer tiered volume pricing
- Example: 0 - 100,000: $.0075; 100,001 - 1,000,000: $.0070; 1,000,000+: $.0065
- Tiers reset on a monthly basis
- Commit Pricing: Offer special discounts to customers in return for a monthly commit
- Set committed amount
- Set overage fee if customer goes above the committed threshold
- Example: $500 commit for 100,000 requests; overage rate: $.0055/request
- Commit pricing resets on a monthly basis and any overage does not roll over to the next month
Tips to help you through the Marketing and Support Submission Form.
The Title, Provider Name, Partner Website or Landing Page, Logo, and Tagline appear in your Add-on detail page as well as in the Catalog.
The Long Description appears in your Add-on listing like in the screenshot below. The field accepts Markdown which is a plain text formatting syntax which converts to structurally valid HTML. Read more about Markdown and how to use it here: https://daringfireball.net/projects/markdown/
You can list up to four highlights. Each highlight requires a Title and Description.
You can list up to three Sample Responses. Each sample response requires a Title, Description and Code Snippet.
Like the Long Description, the Documentation field accepts Markdown. Use this template so that your docs conform to our standard format.
The Requesting Support Process Description accepts Markdown and is a free-form field for you to describe your support process. Customer Support Email and Customer Support Phone will be listed here directly.
The Terms of Service field accepts Markdown. The Privacy Policy field should be a link to your Privacy Policy on your website.
