メニュー

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

公開者 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 instance, Phone Number lookups use a synchronous request/response model. Twilio POSTs data to the partner in a specified format and they reply with a valid result set or error in the response body.

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

パートナー向けAPI要件 - リクエスト

Twilio will be directly consuming the partner'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

You can provide us with the parameters in your API that should be filled with the available template fields for the type of Add-on (refer to the sections below for list of available fields). You should request only those Template Fields that you absolutely require so that Twilio can enable your Add-on across the widest possible range of Integration Points.

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

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

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

The following table lists the Common Template Fields available to you:

テンプレート・フィールド 対応インテグレーション・ポイント アドオンのタイプ 概要
CONSTANT すべて すべて APIパラメーターとしてハードコードされるべき、ベンダー固有の定数データです。
この値はベンダーAPIへの呼び出しごとにTwilioによって渡されます。
{{vendor defined}} Lookup - この表の項目の範囲外の任意のベンダー固有データです。
このパラメーターはAPIを呼び出すユーザーによって明示的に渡される必要があり、Twilioによって自動的に補完されません。
{{request_sid}} すべて すべて Alphanumeric unique identifier for every request. Use if you need a unique identifier in your API.

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

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

認証

現在、Twilio はパートナーの商品ごとに 1 つのアカウントのみサポートしているので、アドオンごとに 1 組のパートナーサービス認証クレデンシャルがサポートされることになります。パートナーは、必要に応じて、提供するすべての商品で 1 組のクレデンシャルを使用することを選択できます。

The following authentication schemes are supported:

  • URL クエリー文字列でクレデンシャルを渡す

  • Passing credentials in the POST request body (www-form-encoded or JSON encoded)

  • HTTP ヘッダーベースの認証(ベーシックまたは Bearer)

既定のHTTPヘッダー

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

ヘッダー名
X-Twilio-AddOnVersionSid 開発者が使用しているアドオンのバージョンを示すユニークな識別子です。

これを使用して、開発者がアドオンの古いバージョンを使用しているかどうかを識別します。
X-Twilio-VendorAccountSid パートナー(お客様自身)のアカウントのアカウント SID です。

例:AC05b3911315a1322d1dede66eed740000
X-Twilio-Signature このリクエストの署名です。パートナーのアカウントによって署名されたものであり、Twilio から受信したリクエストが変更されていないことを確認するために使用します。署名アルゴリズムの詳細については、https://www.twilio.com/docs/api/security の「Twilio からのバリデーションリクエスト」をご覧ください。

例:0FqS203W44/lM2UEM+51hRzwat4=
X-Twilio-RequestSid この特定のパートナーリクエストのユニークな識別子です。課金とデバッグに使用します。

例:MR000009775bb6d43d1cabc4955723fae1
X-Twilio-AddOnSid 呼び出されたアドオンのユニークな識別子です。

これを使用して、このリクエストがどのアドオンで生成されたかを識別します。
X-Twilio-AddOnInstallSid アドオンの開発者インストールのユニークな識別子です。

これを使用して、この特定のアドオンを使用している開発者を区別します。

リクエスト検証スキーマ

If desired, Twilio can validate the Add-on request using a Request Validation JSON Schema prior to invoking your API. This is typically useful in cases where your service cannot fulfill certain requests and you wish to avoid a degraded customer experience or limit the load on your system.

Add-onのリクエストが検証に失敗した場合、Twilioはエラー61003: 「Add-on呼び出しの要件を満たしていません」をユーザーに返し、あなたの提供するサービスの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"}

パートナーAPI要件 - 応答

成功レスポンスとエラーレスポンスはどちらも、標準の JSON オブジェクトフォーマットで返す必要があります。サーバーは、すべてのリクエストに対して、たとえそれがエラーリクエストであっても、2xx レスポンスを返す必要があります。これは、設定の誤りなどの理由により正当に拒否されるリクエストと、SLA に影響を及ぼす可能性があるパートナーエラーを、明確に区別するためです。同期アドオンリクエストが成功した場合は、content-type が application/jason で、ボディーに JSON オブジェクトが格納されている 200 OK レスポンスを返します。非同期アドオンリクエストが成功した場合は、ボディーのない 202 Accepted レスポンスを返します。同期と非同期のどちらのエラーケースも、content-type が application/json で、エラー条件を示す JSON オブジェクトが格納されている 200 OK を返します。

4xx または 5xx のエラーを返した場合、これらはパートナーの設定の誤りまたは機能停止状態とみなされて、エラーレポートシステムに記録され、さらにパートナーの SLA に不利に作用します。Twilio は、4xx エラーを受け取った場合、ただちに失敗リクエストとして処理します。5xx エラーを受け取った場合、最大 N 回または TTL が経過するまで、再試行します。パートナーは、再試行を想定して、request_sid を冪等(繰り返し使用可能)なトークンとして使用する必要があります。

非同期リクエストの場合、非同期タスクの完了後に、パートナーは JSON オブジェクトボディーを Twilio に POST で返します。この JSON ボディーのフォーマットは、成功と失敗のどちらの場合も、上記のフォーマットと同じです。

応答検証スキーマ

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

応答検証スキーマを構築するには: 1. APIの応答をJSON schema generator http://jsonschema.net/ にペーストします。(フィールドからJSON形式でペーストする)

  1. 必須ではない結果からすべてのフィールドを削除します

  2. Schema Validator http://www.jsonschemavalidator.net/ を使用して生成されたスキーマをテストします(コード表示とAdd-on APIからの全応答から生成されたスキーマをペーストし、検証に成功するか確認する)

スキーマ例

たとえば、下記の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要素を指定できます

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

電話番号アドオン

電話番号ルックアップアドオンは、e164 電話番号をクエリーパラメーターとして使用するサードパーティーデータパートナーを公開するために使用します。そのような例として、キャリアディップ、CNAM 発信者 ID ルックアップ、GPS ルックアップ、該当層データベースクエリーなどがあります。

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

呼び出し時に、Twilio から次のフィールドをパートナー 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 は失敗と判断してエラーペイロードを送信し、開発者は課金されません。

メッセージ分析アドオン

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

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

呼び出し時に、Twilio から次のフィールドをパートナー 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 は失敗と判断してエラーペイロードを送信し、開発者は課金されません。

録音分析アドオン

録音分析アドオンタイプは、音声を分析して、結果を構造化データとして返すことができるサードパーティーパートナーを公開するために使用します。この例として、音声トランスクリプション、センチメント分析サービス、音声インデックス化サービスなどがあります。

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

呼び出し時に、Twilio から次のフィールドをパートナー API に渡すことができます。

テンプレート・フィールド 対応インテグレーション・ポイント 概要
{{audio_data}} 録音 Audio file binary bytestream*
{{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}} 録音 音声ファイルのサイズ(バイト)

*The audio data binary bytestream is provided in either 1) HTTP request body (POST/PUT) or 2) HTTP multipart request (POST/PUT) as a part with a name you specify.

This request is asynchronous. A 202 or 204 response with no body is expected upon receiving this request. After processing the audio, partners 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.

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.

Callback SLA

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

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.

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

Twilio とパートナーの間の通信のセキュリティを確保することは、Twilio のセキュリティとパートナーのセキュリティの両方にとって重要です。パートナーは HTTP エンドポイントをインターネットに開放しているので、エンドポイントでパートナーが詐欺や攻撃にさらされないようにあらゆる措置を講じる必要があります。そのために、次に示すさまざまなメカニズムを用意しています。

  1. Twilio は HTTPS/TLSv1.2 のみサポートします。

  2. DDOS 攻撃への露出を軽減するために、Twilio からのリクエストが特定の IP からのみ発信されるようにセットアップできます。Twilio は、この範囲に IP を追加する前にパートナーに連絡します。このようなセットアップを希望する場合は、ご連絡ください。デフォルトの動作では、リクエストは不特定の IP から発信されます。

  3. Twilio は、パートナーの共有シークレットを使用して、すべてのリクエストに署名します。パートナーは、受信したリクエストの署名を検証して、自分の Twilio アカウントからのリクエストであることを確認することを強く推奨します。

  4. Twilio は、呼び出しのたびに、ユニークなリクエスト SID を送信します。パートナーは、リプレーアタックを阻止できるように、これを冪等(繰り返し使用可能)なトークンとして処理することを推奨します。

  5. Twilio は、署名済みペイロードの一部として、呼び出し日時(UTC)と TTL も送信します。パートナーは、(クロックスキューを適度に調節しながら)この TTL をチェックすることで、リプレイ攻撃を阻止できます。

David Prothero Stephen Wai Kat King Andreas Jansson Brent Schooley
Rate this page:

ヘルプが必要ですか?

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.