Add-on Submission Guide
The following guide serves to help you through the Publisher Onboarding process.
Technical Submission Form
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.
Describe what your Add-on does
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.
Documentation for the API that powers the Add-on
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.
Mapping of Add-on template parameters to your API fields
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
GET
https://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.
POST
https://httpbin.org/post?hardcoded_param=STATIC_VALUE
JSON Body
{
"e164": "{{primary_address}}"
"message": "{{body}}"
}
www-form-encoded via POST
POST
https://httpbin.org/post?hardcoded_param=STATIC_VALUE
www-form-encoded Body
key1={{primary_address}}
key2={{secondary_address}}
key3={{body}}
hardcoded_key=STATIC_VALUE
HTTP Headers via GET/POST
GET
https://httpbin.org/get?hardcoded_param=STATIC_VALUE
Headers
key1={{primary_address}}
key2={{secondary_address}}
hardcoded_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.
GET
https://httpbin.org/get?apikey=YOUR_API_KEY&phone_number={{primary_address}}&custom_param={{vendor_defined_field}}
Request Validation Schema
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.
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"primary_address": {
"type": "string",
"pattern": "^\\+(91|1)[0-9]*$"
}
},
"required": [
"primary_address"
]
}
Response Validation Schema
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.
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"args": {
"type": "object",
"properties": {
"e164": {
"type": "string"
}
},
"required": [
"e164"
]
}
},
"required": [
"args"
]
}
Result Cleaning JSON Paths
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.
$.origin
$.headers.Cookie
JSON response before:
{
"args": {
"apikey": "YOUR_API_KEY",
"phone_number": "{{primary_address}}"
},
"headers": {
"Accept": "*/*",
"Accept-Encoding": "gzip, deflate, sdch, br",
"Accept-Language": "en-US,en;q=0.8",
"Cache-Control": "no-cache",
"Cookie": "_cookie=monster",
"Host": "httpbin.org",
"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"
},
"origin": "127.0.0.1",
"url": "https://httpbin.org/get?apikey=YOUR_API_KEY&phone_number={{primary_address}}"
}
JSON response after:
{
"args": {
"apikey": "YOUR_API_KEY",
"phone_number": "{{primary_address}}"
},
"headers": {
"Accept": "*/*",
"Accept-Encoding": "gzip, deflate, sdch, br",
"Accept-Language": "en-US,en;q=0.8",
"Cache-Control": "no-cache",
"Host": "httpbin.org",
"Postman-Token": "60abdc13-1c06-5233-b6dc-00ba98f22070",
"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"
},
"url": "https://httpbin.org/get?apikey=YOUR_API_KEY&phone_number={{primary_address}}"
}
Live Endpoint and Authentication Credentials
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
https://httpbin.org/get?key=YOUR_API_KEY
Request Body via POST
https://httpbin.org/post
www-form-encoded Body
username=TWILIOPROD
password=PASSWORD
HTTP Headers (Basic, Bearer) via GET/POST
Basic/Bearer Auth
https://httpbin.org/get
Username: TWILIOPROD
Password: PASSWORD
OR
Bearer Token: BEARER_TOKEN
Pricing and Billing
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
Marketing and Support Submission Form
Tips to help you through the Marketing and Support Submission Form.
Header
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.
Add-on Long Description and Highlights
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.
Sample Response
You can list up to three Sample Responses. Each sample response requires a Title, Description and Code Snippet.
Documentation
Like the Long Description, the Documentation field accepts Markdown. Use this template so that your docs conform to our standard format.
Support
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.
Legal Submission Form
Policies
The Terms of Service field accepts Markdown. The Privacy Policy field should be a link to your Privacy Policy on your website.
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
