Usage and Migration Guide for Twilio's Node.js Helper Library 3.x

Deprecation notice: New functionality will only be added to the new library (Node Helper Library 3.x). The old library (2.x) is deprecated and Twilio will no longer provide bug fixes. Support might ask you to upgrade before debugging issues.

The Twilio Node Helper Library has undergone a number of changes from version 2.x to 3.x - we'll break down the major changes here to make migrating to the new version as painless as possible. If you're integrating Twilio in your Node app for the first time, you can skip straight to the install page.

ライブラリーのインポート

twilio-node 2.xでは、使用する各クライアントのインスタンスを作成することが必要でした。

var Twilio = require('twilio');
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = 'your_auth_token';

var ipmClient = new Twilio.IpMessagingClient(accountSid, authToken);
var lookupsClient = new Twilio.LookupsClient(accountSid, authToken);

twilio-node 3.xでは今や、インポート、初期化すべきオブジェクトはただひとつです。

var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = 'your_auth_token';

var Twilio = require('twilio');
var twilio = new Twilio(accountSid, authToken);

リソースへのアクセス

// Old
client.messages('SM123').get(function(err, message) {
  console.log(message.sid); //=> SM123
});

// New
client.api.v2010.account.messages('SM123').fetch(function(err, message) {
  console.log(message.sid); //=> SM123
});
// (or)
client.messages('SM123').fetch(function(err, message) {
  console.log(message.sid); //=> SM123
});

新しいライブラリーでは、TwilioのAPIサブドメイン（Lookups、Trunking、Monitorなど）は一級市民です。またTwilio APIへのインスタンスを特定のAPIのバージョンにつなぎとめておくこともできるようになりました（v2010は常にAPIの2010-04-01バージョンとやりとりすることを保証します）。こうすることで、ライブラリーの更新時にフルにアップグレードを行うことなく、コードの一部分のみを将来のバージョンに独立して移行することができます。

また、getがfetchに更新されたことにも気づかれるでしょう。実行されているアクションがより明確になるよう、fetch、create、update、およびremoveを使用するようライブラリーが更新されました。

Promises

またtwilio-nodeとのやり取りにプロミスを使用することもできます。

var promise = twilio.messages('SM123').fetch();
promise.then(function(message) {
  console.log(message.sid);
});

リソースの一覧

リソースの一覧を取得する方法が2種類になりました: listとeachです。

list はリソースのコレクション全体を取得し、リソースのインスタンスを含む配列として解決します。

var promise = twilio.messages.list();
promise.then(function(messages) {
  console.log(messages); //=> [MessageInstance, MessageInstance, MessageInstance, ...]
});

each はリソースの一覧をページ処理し、各インスタンス、それからdone関数を渡すcallback関数を呼び出します。任意の時点で反復処理を停止するには、done関数を呼び出します。

twilio.messages.each(function(message) {
  console.log(message.sid); //=> 'SM123'
});

var i = 0;
twilio.messages.each(function(message, done) {
  console.log(message.sid);

  i++;

  // break after 10 messages
  if (i >= 10) {
    done();
  }
});

ページング

twilio-node 3.xの最大の利点のひとつは、ページ処理を自動で行ってくれることです！ listおよびeachでは、取得するインスタンスの最大数をlimitで、ページサイズをpageSizeで指定できます。後のことはみんなライブラリーにおまかせです。

twilio.messages.each({limit: 10}, function(message) {
  console.log(message.sid);
});

var promise = twilio.messages.list();
promise.then(function(messages) {
  console.log(messages.length); //=> 125
});

promise = twilio.messages.list({
  limit: 100
});
promise.then(function(messages) {
  console.log(messages.length); //=> 100
});

構成可能なHTTPクライアント

独自のHTTPクライアントをTwilioクライアントに接続できるようになりました！ RequestClientインターフェイスに適合したクライアントを、Twilioの初期化時に渡すだけです。

var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = 'your_auth_token';

var client = new CustomClient();
var twilio = new Twilio(accountSid, authToken, client);

TwiML

各TwiMLのタイプ、つまりVoiceおよびMessageごとに専用のコンストラクターを使用するようになりました。

// Old
var TwimlResponse = require('twilio').TwimlResponse;
var twiml = new TwimlResponse();

// New
var MessagingResponse = require('twilio').twiml.MessagingResponse;
var messagingResponse = new MessagingResponse();

var VoiceResponse = require('twilio').twiml.VoiceResponse;
var voiceResponse = new VoiceResponse();

基本的なVoiceResponseについては、パラメーターの順序の変更のみです:

Loading Code Sample...

Next Sample

Show sample response

Example JSON API response

Say動詞内の属性として特定の言語を使用

入れ子にされた動詞は、下記の例のようにコールバック内部で定義される必要はなくなりました。

Loading Code Sample...

Next Sample

Show sample response

Example JSON API response

話し言葉の収集

同様のことは、基本的なMessagingResponseにも当てはまります。

Loading Code Sample...

Next Sample

Show sample response

Example JSON API response

SMSのシンプルな送信

また、こちらは入れ子にされた動詞を含むMessagingResponseの例です:

Loading Code Sample...

Next Sample

Show sample response

Example JSON API response

メディア付きのメッセージ（MMS - 日本未対応）メッセージを送信する

capabilityToken

新しいバージョンでは、新しい機能ごとに専用のコンストラクターが用意されています。

var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = 'your_auth_token';

// Old
var capability = new twilio.Capability(accountSid, authToken);
capability.allowClientIncoming('Identity');
capability.allowClientOutgoing(TWILIO_TWIML_APP_SID);
var token = capability.generate();

// New
var ClientCapability = require('twilio').jwt.ClientCapability;
var capability = new ClientCapability({
  accountSid: accountSid,
  authToken: authToken
});
capability.addScope(new ClientCapability.IncomingClientScope('Identity'));
capability.addScope(new ClientCapability.OutgoingClientScope({
  applicationSid: config.twimlAppSid,
  clientName: identity
}));
var token = capability.toJwt();

APIリクエストのデバッグ

デバッグを容易にするため、ライブラリーでは内部的に使用されるリクエストおよびレスポンスのオブジェクトへのアクセスが行えるようになっています。この機能はライブラリーに内蔵されている既定のHTTPクライアントに内蔵されています。

たとえば、下記のようにして直前のレスポンスのステータスコードを取得できます:

// Twilio Credentials
const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
const authToken = 'your_auth_token';

// require the Twilio module and create a REST client
const client = require('twilio')(accountSid, authToken);

client.messages
  .create({
    to: '+14158675309',
    from: '+14258675310',
    body: 'Ahoy!',
  })
  .then(() => console.log(client.httpClient.lastResponse.statusCode));

例外

3.x has added more descriptive exception handlers.

Now, the exceptions can be caught with the catch() statement.

client.messages.create({
   body: 'Hello from Node',
   to: '+12345678901',
   from: '+12345678901'
}).then(message => console.log(message))
  // here you can implement your fallback code
  .catch(error => console.log(error))

Usage and Migration Guide for Twilio's Node.js Helper Library 3.x

ライブラリーのインポート

リソースへのアクセス

Promises

リソースの一覧

ページング

構成可能なHTTPクライアント

TwiML

Say動詞内の属性として特定の言語を使用

話し言葉の収集

SMSのシンプルな送信

メディア付きのメッセージ（MMS - 日本未対応）メッセージを送信する

capabilityToken

APIリクエストのデバッグ

例外

関連トピックとサポート

ヘルプが必要ですか？

ヘルプが必要ですか？

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

Thanks for your feedback!

ステップ1

ステップ2:

ステップ3