メニュー

Expand
ページを評価:

アドオン公開者ガイド

The Twilio Marketplace is an API-enabled platform for 3rd parties to offer products and services that are built on or complementary to Twilio’s products, for sale to Twilio’s massive developer community.

Developers can discover & install API-driven services via a central self-serve marketplace experience and invoke them in a standard manner as part of the core Twilio API. Twilio manages the listing, configuration, developer facing API points, billing and publisher payment for its third party offerings.

This Guide is designed for 3rd party publishers who wish to integrate their services into the Twilio Marketplace in the form of an Add-on. It provides an overview of marketplace offerings and API requirements.


アドオンの概要

At a functional level, Add-ons package publisher APIs, and annotate the content that Twilio provides by tapping into the publisher’s data sources or using a publisher’s technology to analyze the content. Examples include phone number based queries for demographic & marketing data, number fraud/spam block list, Recordings Transcription, message sentiment analysis, etc.

Currently, the following Twilio content is available for Add-on publishers to build with: phone numbers, incoming message bodies, call recordings.

アドオンのタイプ 統合ポイント Data available to Publishers 利用モード
電話番号アドオン ルックアップ、着信 SMS、着信音声通話 電話番号(単一、発信元、発信先) 同期
メッセージ分析アドオン 着信SMS 電話番号、メッセージ本文 同期
録音分析アドオン 録音 音声ファイル(単一チャンネル) 非同期

開発者は、アドオンを選択して、自分のアカウントに合わせて設定することによって、使用できるようにします。その後は、サポート用 Twilio API を使用したときにアドオンが呼び出されるように、指定することができます。

The figure below illustrates the timeline and flow of information between a developer, Twilio, and a publisher’s Add-on. If a developer set up a recording add-on to respond to voice calls, The voice call would be accepted by Twilio, and sent to the developer’s webhook. Afterwards, the call could be recorded and the information sent back to Twilio. Twilio would then give the data to the recording add-on for processing, and once the Add-on returns the relevant data to Twilio, Twilio would return the data to the developer.

画像の alt テキスト

料金と課金

The Twilio Marketplace works as a platform to allow publishers to share their add-ons with developers. Add-on publishers set their own pricing scheme and then invoke the Twilio Billing System, which meters usage of add-ons by developers and proceeds to deduct credit from the developer’s account. Finally, the billed amounts are distributed to add-on publishers, via invoice, after Twilio levies a transaction fee.

Publishers can choose to package one service/API into one Add-on, or deliver a service/API as multiple Add-ons. Delivering a service as multiple Add-ons may allow developers to adjust their expenses in accordance to their usage or the extent of which they need your Add-on, such as processing personal or business data sets, or transcribing various languages.

Since add-on publishers set their own pricing scheme, billing models may be different between add-ons. The following billing models are supported by the Marketplace for an Add-on:

  • 使用回数型
  • Pay-per-success (TBD): Conditional billing subject to absence of certain JSON elements in the response and HTTP status codes.
  • Pay-per-minute: For Transcription / Recording Add-ons

Publisher Accounts

Currently, Twilio supports one ‘source’ account per Publisher offering, and will use that to make all API requests.

To illustrate an example of how your account will make API requests and how that will function as an add-on, let’s say you have a web service that takes a phone number and returns all the English mnemonics you can spell with it. You’d like to let any Twilio customer dip your service via the Twilio Lookup API to see potential results, and you want to charge $0.0001 per lookup.

これが次の API で提供されるとします(クレデンシャルについてはとりあえず無視します)。

https://www.example.com/twilio_phone_number_example  -d "e164=+18778894546"

Results in the following JSON response:

{
"anagrams": ["+18778TWILIO", ...]
}

You would deliver this service as a marketplace Add-on -- ‘Anagram’. A Twilio developer finds and installs this service on their account. They now would have the ability to use the Anagram Add-on in the Lookup API, when buying/provisioning phone numbers, receiving incoming calls or messages, or making outgoing calls or messages, if appropriate. Afterwards, they would be able to make the following cURL request

curl -X GET https://lookups.twilio.com/v1/PhoneNumbers/18778894546\
-d "AddOns=publisher_anagrams" -u "{TwilioAccountSid}:{TwilioAuthToken}"

これは、次のボディーを含む 200 OK レスポンスを返します。

{
    "country_code": "US",
    "phone_number": "+18778894546",
    "national_format": "1 (877) 889-4546",
    "url": "https://lookups.twilio.com/v1/PhoneNumber/+551155256325",    
    "add_ons": {  
           "status": "successful",
           "message": null,
           "code": null,
           "results": {      
                    "publisher_anagrams": {
                           "request_sid": "XRc1479687aadf64c62e6ab2b6e0077a1a",
                           "status": "successful",
                           "message": null,
                           "code": null,
                           "result": {
                                   "anagrams": ["+18778TWILIO"]
                           }                           
                    }
            }
    }
}

呼び出されると、Twilio が開発者の HTTP サービスを呼び出して、リクエストされた電話番号を POST します。結果を受け取ると、その中の JSON ボディーを取り出して、リクエストされた他のタイプとともに、レスポンスのペイロードに格納します。

探し方と使い方

開発者は、コンソールで Marketplace を使用してアドオンを探して、インストールします。このプロセスの詳細については、「アドオンの概要」をご覧ください。

Add-onのAPI要件

These specifications will detail how Twilio will make requests to your service, what fields you can expect for each supported Add-on type, and how their success and error responses must be formatted and returned.

For most Add-on types, the interface is a simple RESTful HTTP protocol. For Add-ons such as phone number lookup, a synchronous request/response model is used, where Twilio POSTs data to the publisher in a specified format and they reply with a valid result set or error in the response body.

For other Add-ons, such as recording analysis, an asynchronous model is used, where Twilio POSTs data to the publisher and expects a 202 Accepted response back. The publisher would then post back to a REST API exposed by Twilio to report results back some time later. In this model, Twilio will ask the developer for a callback URL at configuration time, and take responsibility for relaying any async results back to them.

Publisher API Requirements - Requests

Twilio will be directly consuming publisher's JSON/REST API, and transforming the returned data and error codes to a format compatible with the Twilio API style and format.

API パラメーター

Twilioは、ひとつ以上の下記パラメーターを通じて、Add-on用のAPIにテンプレート項目や定数といったベンダー固有のフィールドを渡すことをサポートしています。

APIパラメーター リクエスト型
Querystring パラメーター GET, POST
JSONディクショナリー POST
www-form-encoded POST
HTTPヘッダー GET, POST

Add-onのタイプについて利用可能なテンプレート・フィールドを満たしたAdd-onのAPIパラメーターをTwilioに提供できます。 (利用可能なフィールドの一覧については、下記セクションをご確認ください) TwilioがAdd-onをインテグレーション・ポイントで極力広範に有効にできるよう、絶対必須なテンプレート・フィールドのみをリクエストするようにしてください。

また、ユーザーが設定可能なパラメーター、特定の値にハードコード化する必要があるパラメーター、および開発者がリクエストの際に指定する必要があるパラメーターを通知することもできます。

現時点で、Lookupのみがリクエスト時パラメーターをサポートしていることにご注意ください。

共通テンプレート・フィールド

下記の表は、利用可能な共通テンプレート・フィールドの一覧です。

テンプレート・フィールド 対応インテグレーション・ポイント アドオンのタイプ 概要
CONSTANT すべて すべて APIパラメーターとしてハードコードされるべき、ベンダー固有の定数データです。
この値はベンダーAPIへの呼び出しごとにTwilioによって渡されます。
{{request_sid}} すべて すべて 全リクエスト用の英数字からなる一意の識別子。 Add-onのAPIで一意な識別子が必要な場合に使用します。
{{vendor defined runtime field}} Lookup - この表の項目の範囲外の任意のベンダー固有データです。
このパラメーターはAPIを呼び出すユーザーによって明示的に渡される必要があり、Twilioによって自動的に補完されません。
{{custom configuration field}} すべて すべて この表の項目の範囲外の任意のベンダー固有データです。
このパラメーターはユーザーによってコンソール上から設定され、Twilioによって自動的に補完されません。
{{SHA256:template_field}} すべて すべて SHA256 hash of any field, e.g. {{SHA256:primary_address}} for SHA256 hash of {{primary_address}} template field in Phone Number integration
{{unix_timestamp}} すべて すべて Unix timestamp

Add-onタイプ固有のテンプレート・フィールド

使用可能な追加のテンプレート・フィールドについては、「特定のAdd-onタイプの必須要件」セクションをご確認ください。

カスタム設定のテンプレート・フィールド

たとえば、Add-onのAPIに追加のパラメーターを渡すことが必要とされる場面では、ユーザーがコンソール上から設定可能なカスタム・フィールドを定義できます。 ひとたび設定が済むと、TwilioはこれらのパラメーターをAdd-onのAPIに他のテンプレート・フィールドと同様に渡します。

User configurable parameters are specified as a JSON schema, provided in the "Configuration JSON Schema". These parameters are mapped into the corresponding UI elements inside console, and the configured values are made available to the Add-on as template fields.

Configuration JSON Schema supports the following JSON elements:

Type-specific Keywords:
  • string (presented as a text field in the UI)
  • number & integer (presented as text field in UI with number validation)
  • boolean (presented as checkbox in UI)

Note: object and array keywords are not supported

Generic keywords:
  • enum (presented as a dropdown list)
  • name (used to render the field label in the UI)
  • _help (used to render a tooltip next to the field in the UI)
  • element_name in the schema is used to define the template variable name.
Combining Schemas and Regular expressions :
  • Supported for input validation and the relevant error message shall be displayed when the input does not validate against the configuration schema.

スキーマ例:

{
  "title": "Config schema",
  "type": "object",
  "properties": {
    "language": {
      "type": "string",
      "name": "Language",
      "_help": "Select the language for your recordings: US English (en_US), UK English (en_UK), Spanish (es)",
      "enum": ["en_US","en_UK","es"]
    },
    "combine_tracks": {
      "type": "boolean",
      "name": "Combine Audio Tracks",
      "_help": "Combine transcriptions from different tracks into one list or keep them separated"
    },
    "keywords": {
      "type": "string",
      "name": "Keywords to detect",
      "_help": "Identify the presence and timestamps for these keywords (Comma separated) in the audio"
    },
    "phone_number": {
      "type": "string",
      "name": "Phone Number",
      "_help": "E164 formatted phone numbers. Only +1 prefixes allowed",
      "pattern": "^\\+(1)+[0-9]*$"
    }
  },
  "required": [
    "language"
  ]
}

このスキーマは以下のようなUIを生成し、これらのテンプレート・フィールドを作成: {{language}}{{combine_tracks}}{{keywords}}、そして{{phone_number}} が、Add-onのAPI中で利用できます。

コンソール内でのAdd-onの設定

認証

Since Twilio currently only supports one account per Publisher offering, it follows that there will be one set of authentication credentials for the Publisher’s service supported per Add-on. The Publisher can choose to use a single set of credentials across all their offerings if so desired.

次の認証スキームがサポートされています。

  • URL クエリー文字列でクレデンシャルを渡す
  • POST リクエストボディーでクレデンシャルを渡す(WWW フォームエンコード済みまたは JSON エンコード済み)
  • HTTP ヘッダーベースの認証(ベーシックまたは Bearer)

既定のHTTPヘッダー

Twilio will always pass the following set of headers along with the GET/POST request to the publisher API that may be used for security and debugging purposes if the publisher so desires.

ヘッダー名
X-Twilio-VendorAccountSid The Account Sid of the publisher (your) account.

Example: AC05b3911315a1322d1dede66eed740000
X-Twilio-Signature The signature of this request, signed by the publisher’s account, and used to verify the request came from Twilio unmodified. See the "Validating Requests are coming from Twilio" section here for details of signature algorithm: https://www.twilio.com/docs/api/security

Example: 0FqS203W44/lM2UEM+51hRzwat4=
X-Twilio-RequestSid The unique identifier of this particular publisher request. Used for billing and debugging.

Example: MR000009775bb6d43d1cabc4955723fae1
X-Twilio-AddOnSid The unique identifier for the Add-on being invoked.

Use this to identify which of your Add-ons is generating this request.
ex. XBc6dc06ce91d566fae284bc2bf36218a4
X-Twilio-AddOnVersionSid The unique identifier of the Add-on version being used by the developer.

Use it to identify if the developer is using an older version of your Add-on.
ex. XC2ad3d7d6478a2ca72f224d817a241586
X-Twilio-AddOnInstallSid The unique identifier for a developers install of an Add-on.

Use this to distinguish between developers using this particular Add-on.
ex. XDe2767c53b3d7be099a825252c6cf4e59
X-Twilio-AddOnConfigurationSid The unique identifier for an instance of the installed Add-on.
ex. XEbee2b4cf26384f0b88ad98a25530c338

リクエスト検証スキーマ

望むならば、TwilioはAdd-onのAPI呼び出しに先だって、リクエスト検証JSONスキーマを使用しAdd-onのリクエストを検証することができます。 これは通常、サービスがあるリクエストをまっとうできず、顧客体験の低下を防いだり、システムへの負荷を制限したい場合に有用です。

When an Add-on request fails to validate, Twilio will return Error 61003: "Requirements to invoke Add-ons have not been met" to the user and will not count it against your SLA.

リクエスト検証スキーマは、上記のテンプレート・フィールドを含むJSONディクショナリーに対して適用されます。

JSONスキーマのツール

スキーマ例

Add-onに特定の数字で始まる電話番号を制限するのに使用できます。 この例では+91または+1で始まる電話番号のみに制限するよう、ベンダーAdd-onに制限させます。

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "primary_address": {
      "type": "string",
      "pattern": "^\\+(91|1)+[0-9]*$"
    }
  },
  "required": [
    "primary_address"
  ]
}

入力JSONのフィールドを下記のようにスキーマ・バリデーターを設定し、さまざまなスキーマをテストしてください: {"primary_address": "+12345678901"}|

Publisher API Requirements - Responses

Both success and error responses are expected to be in a standard JSON object format. The server is expected to return a 2xx response for all requests, even error requests. This is to disambiguate publisher errors that may affect SLA from legitimately rejected requests due to misconfiguration or other. For successfully synchronous Add-on requests, a 200 OK response is expected, with a content-type application/json and a JSON object returned in the body. For successful asynchronous Add-on requests, a 202 Accepted response is expected, with no body returned. For both sync and async cases error cases, a 200 OK is expected with a content-type application/json and a JSON object describing the error condition.

Any 4xx or 5xx errors returned will be considered publisher misconfiguration, or outage, will be logged in the error reporting system and will count against the publisher's SLA. For 4xx errors, Twilio will fail the request immediately. For 5xx errors, Twilio will retry up to N times, or until the TTL has passed. Publishers should expect retries, using the request_sid as an idempotency token.

For async requests, the publisher is responsible for POSTing back the JSON object body to Twilio once the async task is completed. This JSON body will be the same format as above, for both success or failure.

応答検証スキーマ

指定があった場合、応答検証スキーマは応答に対して有効とみなされる最低限の特定フィールドが含まれることを確実にしてから、ユーザーに対して請求を行います。

To build a Response Validation Schema: 1. Paste your API response into the JSON schema generator: http://jsonschema.net/ (paste in JSON form field) 2. Delete all the fields from the result that are not required 3. Test Schema generated using the schema validator: http://www.jsonschemavalidator.net/ (Paste generated Schema from Code View and the full response from your API and ensure it validates)

スキーマ例

たとえば、下記のAdd-on APIからの応答をが常に args.e164 パラメーターが含まれることを有効とみなすように検証したい場合。

API応答の例

{
  "args": {
    "e164": "+13233633791",
    "test": "1"
  },
  "origin": "184.73.170.150",
}

JSONスキーマ

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "args": {
      "type": "object",
      "properties": {
        "e164": {
          "type": "string"
        }
      },
      "required": [
        "e164"
      ]
    }
  },
  "required": [
    "args"
  ]
}

応答クリーニング

応答クリーニングJSONパスを使用して、応答から特定の要素を削除するようTwilioに指示します。これには通常、APIキーが(返される場合)、使用状況カウンター、ベンダー固有のリソースURIなどが含まれます。

JSONパスを削除するのに、ひとつ以上のJSON要素を指定できます

個別のアドオンタイプの要件

電話番号アドオン

The Phone Number Lookup Add-on is used to expose 3rd party data publishers that use an e164 phone number as their query parameter. Examples of these are carrier dips, CNAM caller ID lookups, GPS lookups, demographic database queries, and so forth.

アドオンリクエストのフィールド

When invoked, Twilio can supply the following fields to the publisher API.

テンプレート・フィールド 対応インテグレーション・ポイント 概要
{{primary_address}} 受信SMS、着信通話、Lookup 調べる電話番号(e164 フォーマット)。 +<country code><phone number>
{{secondary_address}} 受信SMS、着信通話 To 番号(e164 フォーマット) +<country code><phone number>

これは同期リクエストです。有効なレスポンスボディーを格納した 200 OK を返す必要があります。

アドオンの SLA

このリクエストへの応答は、ルックアップ API リクエストの一部として、または通話または SMS セットアップのフローで、同期的に行われるので、パフォーマンスが重要になります。これを公開するサービスは、平均約 200ms で応答し、その 99% は 1500ms 未満である必要があります。リクエストへの応答時間が 2000ms を超えると、Twilio は失敗と判断してエラーペイロードを送信し、開発者は課金されません。

アドオンレスポンスのサイズ制限

同期的なアドオンなので、これに対するレスポンスは最大 50KB に制限されます。レスポンスのサイズがこの最大値を超えると、Twilio は失敗と判断してエラーペイロードを送信し、開発者は課金されません。

メッセージ分析アドオン

メッセージ分析アドオンは、コンテンツを分析するサードパーティーにメッセージの本文を渡します。例として、翻訳や意図分析が考えられます。

アドオンリクエストのフィールド

When invoked, Twilio can supply the following fields to the publisher API.

テンプレート・フィールド 対応インテグレーション・ポイント 概要
{{primary_address}} 着信SMS 調べる電話番号(e164 フォーマット)。 +<country code><phone number>
{{secondary_address}} 着信SMS To 番号(e164 フォーマット) +<country code><phone number>
{{body}} 着信SMS SMSメッセージ中のUTF-8エンコーディングされた本文

これは同期リクエストです。有効なレスポンスボディーを格納した 200 OK を返す必要があります。

アドオンの SLA

このリクエストへの応答は、SMS 配信フローで同期的に行われるので、パフォーマンスが重要になります。これを公開するサービスは、平均約 200ms で応答し、その 99% は 1500ms 未満である必要があります。リクエストへの応答時間が 2000ms を超えると、Twilio は失敗と判断してエラーペイロードを送信し、開発者は課金されません。

アドオンレスポンスのサイズ制限

同期的なアドオンなので、これに対するレスポンスは最大 64KB に制限されます。レスポンスのサイズがこの最大値を超えると、Twilio は失敗と判断してエラーペイロードを送信し、開発者は課金されません。

録音分析アドオン

The Recording Analysis Add-on Type is used to expose 3rd party publishers who can analyze audio and return results as structured data. Examples of this are audio transcription, sentiment analysis services, audio indexing services, etc.

アドオンリクエストのフィールド

When invoked, Twilio can supply the following fields to the publisher API.

テンプレート・フィールド 対応インテグレーション・ポイント 概要
{{audio_data}} 録音 Audio file binary bytestream, in HTTP request body or HTTP multipart request (POST/PUT) with a name you specify
{{callback_url}} 録音 分析結果を返すために 1 回だけ使用する URL
{{channels}} 録音 音声ファイルのチャンネル数
{{duration}} 録音 Duration of the audio in milliseconds
{{format}} 録音 Audio Mimetype. Default recording format is audio/x-wav
{{media_sid}} 録音 レコーディングSID
{{size}} 録音 音声ファイルのサイズ(バイト)

This request is asynchronous. A 202 or 204 response with no body is expected upon receiving this request. After processing the audio, publishers are expected to POST the JSON results to the Callback URL within the request timeout agreed upon. After the timeout expires, the request will be considered failed, and the developer will not be billed.

Add-on Callback Authentication

To authenticate the Callback HTTP request containing the audio analysis, we ask that you use basic authentication with the Account SID and Auth Token or an API Key (https://www.twilio.com/console/dev-tools/api-keys) created from the vendor account that the Add-on belongs to.

Add-on Callback SLA

このリクエストへの応答は非同期的に行われるので、厳しい要件はありません。これを公開するサービスは、音声ファイルの長さの平均 3 倍の時間で応答し、その 99% は 5 倍未満であるようにすることを推奨します。リクエストへの応答時間が音声ファイルの長さの 10 倍の時間を超えると、Twilio は失敗と判断してエラーペイロードを送信し、開発者は課金されません。

Add-on Callback Size Limit

As an asynchronous Add-on, the response for this is limited to a maximum of 100 MB. Any response larger than this maximum will be failed by Twilio, an error payload will be sent, and the developer will not be billed.

セキュリティとプライバシーの要件

It is important to secure communication between Twilio and publishers, for both Twilio's security as well as the publisher's. Because publishers are opening up an HTTP endpoint to the public internet, all efforts should be made to make certain that endpoint does not expose the publisher to fraud or attack. To ensure this, a number of mechanisms will be in place

  1. Twilio は HTTPS/TLSv1.2 のみサポートします。
  2. To help mitigate any DDOS attack exposure, Twilio requests can be setup to only come from specific IPs. Twilio will contact publishers before adding any IPs to this range. If you require such a setup, let us know. The default behavior is that they will not come from specific IPs.
    1. 174.129.222.33
    2. 174.129.222.200
    3. 184.73.170.150
    4. 23.21.226.67
  3. Twilio signs every request with the publisher's shared secret key. Publishers are strongly encouraged to validate the signature of the requests they receive to confirm they're coming from their Twilio account.
  4. Twilio sends a unique request SID with each invocation. Publishers are encouraged to treat this as an idempotency token, allowing them to thwart replay attacks.
  5. Twilio also sends an invocation date(UTC) and TTL as part of each signed payload. Checking this TTL(with a reasonable accomodation for clock-skew) further protects publishers from replay attacks.
ページを評価:

ヘルプが必要ですか?

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.

        
        
        

        フィードバックくださりありがとうございます!

        Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        ステップ1

        Get link

        Get a free personal referral link here

        ステップ2:

        Give $10

        Your user signs up and upgrade using link

        ステップ3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more