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:

  1. Single Price: Regardless of volume usage, customer will be charged a flat unit rate
    • Example: $.0080/unit
  2. 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
  3. 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.

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.

Header

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.

Description

Sample Response

You can list up to three Sample Responses. Each sample response requires a Title, Description and Code Snippet.

Snippets

Documentation

Like the Long Description, the Documentation field accepts Markdown. Use this template so that your docs conform to our standard format.

Documentation

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.

Support

Policies

The Terms of Service field accepts Markdown. The Privacy Policy field should be a link to your Privacy Policy on your website.

Policies

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 browsing the Twilio tag on Stack Overflow.