Twilio Pythonライブラリ徹底解説：SMS送信から電話、Webhooks連携まで

Twilioを使えば、非常に簡単にプログラムからSMSを送信できます。これは、ユーザーへの通知、二段階認証コードの送信、マーケティングメッセージの配信など、多くの用途に活用できます。

SMSを送信するには、client.messages.create() メソッドを使用します。最低限必要な情報は以下の通りです。

• to: 送信先の電話番号 (E.164形式: 例 `+819012345678`)
• from_: 送信元となるTwilioの電話番号 (Twilioコンソールで購入したもの) またはメッセージングサービスSID
• body: 送信するメッセージ本文

以下は、SMSを送信する基本的なコード例です。

import os
from twilio.rest import Client
from twilio.base.exceptions import TwilioRestException
# 環境変数から認証情報を取得 (前述の通り設定済みとする)
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
auth_token = os.environ["TWILIO_AUTH_TOKEN"]
twilio_phone_number = os.environ["TWILIO_PHONE_NUMBER"] # 送信元となるTwilio電話番号
recipient_phone_number = "+819012345678" # 送信先の電話番号 (実際の番号に置き換える)
client = Client(account_sid, auth_token)
message_body = "こんにちは！これはTwilio Pythonライブラリからのテストメッセージです。"
try: message = client.messages.create( to=recipient_phone_number, from_=twilio_phone_number, body=message_body ) print(f"メッセージが正常に送信されました！ SID: {message.sid}") print(f"メッセージ本文: {message.body}")
except TwilioRestException as e: print(f"メッセージの送信に失敗しました: {e}")

上記のコードでは、from_ にTwilioで購入した電話番号を指定しています。代わりに、メッセージングサービスを作成し、そのSID (messaging_service_sid) を指定することもできます。メッセージングサービスを利用すると、複数の番号を束ねたり、送信元番号の選択ロジック（ジオマッチなど）を利用したり、様々な高度な機能が使えます。

# メッセージングサービスSIDを使う場合の例
# message = client.messages.create(
# to=recipient_phone_number,
# messaging_service_sid="MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", # メッセージングサービスSIDを指定
# body=message_body
# )

MMS (Multimedia Messaging Service) を送信して画像などのメディアファイルを含めることも可能です。その場合は media_url パラメータに公開されている画像のURLを指定します。

# MMSを送信する例 (画像付き)
# try:
# message = client.messages.create(
# to=recipient_phone_number,
# from_=twilio_phone_number,
# body="素敵な画像を送ります！",
# media_url=["https://c1.staticflickr.com/3/2899/14341091933_1e92e62d12_b.jpg"] # 公開されている画像のURLリスト
# )
# print(f"MMSが正常に送信されました！ SID: {message.sid}")
#
# except TwilioRestException as e:
# print(f"MMSの送信に失敗しました: {e}")

Twilio Pythonライブラリを使えば、プログラムから電話を発信することも簡単です。自動音声案内、クリック・トゥ・コール、通知のための発信などに利用できます。

電話を発信するには、client.calls.create() メソッドを使用します。主なパラメータは以下の通りです。

• to: 発信先の電話番号 (E.164形式)
• from_: 発信元となるTwilioの電話番号 (音声通話機能が有効なもの)
• twiml: 通話が接続された後にTwilioが実行する指示を記述したTwiML (XML形式の文字列)。
• url: twiml の代わりに、TwiMLを返す公開URLを指定することもできます。

TwiML (Twilio Markup Language) は、Twilioに通話中の動作を指示するためのXMLベースの言語です。例えば、メッセージを読み上げさせたり(<Say>)、音声ファイルを再生させたり(<Play>)、ユーザーからの入力を受け付けたり(<Gather>) することができます。

以下は、指定した番号に電話を発信し、接続後に簡単なメッセージを読み上げるコード例です。

import os
from twilio.rest import Client
from twilio.base.exceptions import TwilioRestException
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
auth_token = os.environ["TWILIO_AUTH_TOKEN"]
twilio_phone_number = os.environ["TWILIO_PHONE_NUMBER"] # 音声通話可能なTwilio番号
recipient_phone_number = "+818012345678" # 発信先の電話番号 (実際の番号に置き換える)
client = Client(account_sid, auth_token)
# TwiMLを文字列で作成 (接続後にメッセージを読み上げる)
twiml_instructions = """
<Response> <Say language="ja-JP" voice="alice">こんにちは。これはTwilio Pythonからの自動発信テストです。</Say> <Play>http://demo.twilio.com/docs/classic.mp3</Play>
</Response>
"""
try: call = client.calls.create( to=recipient_phone_number, from_=twilio_phone_number, twiml=twiml_instructions # url="http://demo.twilio.com/docs/voice.xml" # TwiMLを返すURLを指定することも可能 ) print(f"電話の発信を開始しました！ Call SID: {call.sid}")
except TwilioRestException as e: print(f"電話の発信に失敗しました: {e}")

上記の例では、twimlパラメータに直接XML文字列を渡しています。<Say>タグで日本語のメッセージを読み上げ、<Play>タグでMP3ファイルを再生するように指示しています。 より複雑なTwiMLを生成する場合は、Twilio PythonライブラリのTwiML生成クラス (twilio.twiml.voice_response.VoiceResponse) を使うと便利です。

Twilioの電話番号宛にSMSメッセージや電話着信があった際に、特定の動作をさせたい場合があります。例えば、受信したSMSに応じて自動返信を行ったり、電話着信時に自動音声応答（IVR）を流したりするケースです。

これを実現するのがWebhookとTwiMLです。Twilio番号へのイベント（SMS受信、電話着信など）が発生すると、Twilioは事前に設定されたあなたのアプリケーションのURL（Webhook URL）にHTTPリクエストを送信します。あなたのアプリケーションはそのリクエストを受け取り、実行すべき指示をTwiML形式でTwilioにレスポンスとして返す必要があります。

Twilio Pythonライブラリには、このTwiMLを簡単に生成するためのクラスが用意されています。

• 音声通話用: twilio.twiml.voice_response.VoiceResponse
• SMS/MMS用: twilio.twiml.messaging_response.MessagingResponse

以下は、Flaskフレームワークを使用して、着信SMSに対して自動返信する簡単なWebhookの例です。

from flask import Flask, request, Response
from twilio.twiml.messaging_response import MessagingResponse
app = Flask(__name__)
@app.route("/sms", methods=['POST'])
def sms_reply(): """受信したSMSメッセージに対して応答する""" # 受信したメッセージ本文を取得 incoming_msg = request.values.get('Body', '').lower() sender_number = request.values.get('From', '') # MessagingResponseオブジェクトを作成 resp = MessagingResponse() # 受信内容に応じて応答メッセージを作成 if 'こんにちは' in incoming_msg: reply_text = f"{sender_number}さん、こんにちは！" elif 'ありがとう' in incoming_msg: reply_text = "どういたしまして！" else: reply_text = "メッセージありがとうございます！「こんにちは」または「ありがとう」と送ってみてください。" # 応答メッセージをTwiMLに追加 resp.message(reply_text) # TwiMLレスポンスを生成して返す (Content-Type: text/xml) return Response(str(resp), mimetype='text/xml')
if __name__ == "__main__": # 開発用サーバーを起動 (本番環境ではGunicornなどを使用) # ngrokなどを使って外部からアクセス可能なURLを取得し、TwilioコンソールでWebhook URLとして設定する app.run(debug=True, port=5000)

このコードでは、Flaskを使って/smsというエンドポイントを作成しています。TwilioからSMS受信時にこのURLにPOSTリクエストが送られてくると、受信メッセージ本文 (Body) を取得し、内容に応じて返信メッセージを生成します。MessagingResponseオブジェクトのmessage()メソッドを使って応答TwiML (<Message>タグ) を構築し、XML形式でレスポンスしています。

同様に、VoiceResponseを使えば、電話着信時に<Say>や<Gather>などの動詞を使って音声応答フローを構築できます。

from flask import Flask, request, Response
from twilio.twiml.voice_response import VoiceResponse, Gather
app = Flask(__name__)
@app.route("/voice", methods=['POST'])
def voice_menu(): """電話着信時に音声メニューを流す""" resp = VoiceResponse() # Gatherを使ってユーザーからの入力を受け付ける gather = Gather(num_digits=1, action='/handle-key', method='POST', language='ja-JP') gather.say('お電話ありがとうございます。オペレーターにお繋ぎする場合は1を、メッセージを残す場合は2を押してください。') resp.append(gather) # 何も入力されなかった場合の処理 resp.say('入力がありませんでした。お電話ありがとうございました。', language='ja-JP') resp.hangup() return Response(str(resp), mimetype='text/xml')
@app.route("/handle-key", methods=['POST'])
def handle_key(): """ユーザーが押したキーに応じて処理を分岐""" digit_pressed = request.values.get('Digits', None) resp = VoiceResponse() if digit_pressed == '1': resp.say('オペレーターにお繋ぎします。', language='ja-JP') # ここでオペレーターの番号に転送するなどの処理 # resp.dial('+81xxxxxxxxxx') resp.hangup() # 今回は切断 elif digit_pressed == '2': resp.say('メッセージをどうぞ。録音を開始します。ピーという音の後にお話しください。', language='ja-JP') resp.record(action='/handle-recording', method='POST', max_length=30, finish_on_key='*') resp.say('録音が完了しませんでした。お電話ありがとうございました。', language='ja-JP') # recordが失敗した場合など resp.hangup() else: resp.say('無効な入力です。お電話ありがとうございました。', language='ja-JP') resp.hangup() return Response(str(resp), mimetype='text/xml')
@app.route("/handle-recording", methods=['POST'])
def handle_recording(): """録音完了後の処理""" recording_url = request.values.get('RecordingUrl', None) resp = VoiceResponse() if recording_url: resp.say('メッセージをお預かりしました。ありがとうございました。', language='ja-JP') # 録音URLを使って何か処理を行う (例: 保存、通知など) print(f"録音ファイルURL: {recording_url}") else: resp.say('録音に失敗しました。申し訳ありません。', language='ja-JP') resp.hangup() return Response(str(resp), mimetype='text/xml')
if __name__ == "__main__": app.run(debug=True, port=5000)

これらのWebhookを動作させるには、ローカル開発環境を外部に公開する必要があります。ngrokのようなツールを使うと、一時的に公開URLを生成でき、開発・テストに便利です。本番環境では、公開されたサーバーにアプリケーションをデプロイする必要があります。Webhook URLはTwilioコンソールの各電話番号の設定画面で指定します。

Twilio Lookup APIを使うと、電話番号に関する様々な情報を取得できます。例えば、番号が有効かどうか、携帯電話番号か固定電話か、どのキャリアに属しているかなどを確認できます。これは、ユーザー登録時の番号検証、不正利用の防止、SMS配信の最適化などに役立ちます。

Pythonライブラリでは、client.lookups.v2.phone_numbers('(電話番号)').fetch() メソッドを使って情報を取得します。(v1 API も存在しますが、v2 が推奨されています)

基本的な情報（フォーマット、有効性）の取得は無料です。キャリア情報などを取得するには、追加のデータパッケージ (fields パラメータで指定) が必要となり、有料になる場合があります。

import os
from twilio.rest import Client
from twilio.base.exceptions import TwilioRestException
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
auth_token = os.environ["TWILIO_AUTH_TOKEN"]
client = Client(account_sid, auth_token)
phone_number_to_lookup = "+16502530000" # 例: Googleの公開番号 (実際は検証したい番号)
# phone_number_to_lookup = "+819012345678" # 日本の番号の場合
try: # 基本的なLookup (無料) print(f"--- 基本Lookup ({phone_number_to_lookup}) ---") basic_info = client.lookups.v2 \ .phone_numbers(phone_number_to_lookup) \ .fetch() print(f"有効な番号か: {basic_info.valid}") if basic_info.valid: print(f"E.164形式: {basic_info.phone_number}") print(f"国コード: {basic_info.country_code}") print(f"国内形式: {basic_info.national_format}") # print(f"検証結果: {basic_info.validation_errors}") # エラーがある場合 else: print(f"無効な番号です。エラー: {basic_info.validation_errors}") # Carrier情報を追加で取得 (有料の場合あり) print(f"\n--- Carrier情報Lookup ({phone_number_to_lookup}) ---") carrier_info = client.lookups.v2 \ .phone_numbers(phone_number_to_lookup) \ .fetch(fields='carrier') # carrier情報を要求 if carrier_info.valid and carrier_info.carrier: print(f"キャリア名: {carrier_info.carrier.get('name')}") print(f"回線種別: {carrier_info.carrier.get('type')}") # 例: mobile, landline, voip print(f"エラーコード: {carrier_info.carrier.get('error_code')}") # nullなら成功 elif not carrier_info.valid: print(f"無効な番号です。エラー: {carrier_info.validation_errors}") else: print("キャリア情報を取得できませんでした。") # Line Type Intelligence (LTI) を追加で取得 (有料の場合あり) # print(f"\n--- Line Type Intelligence Lookup ({phone_number_to_lookup}) ---") # lti_info = client.lookups.v2 \ # .phone_numbers(phone_number_to_lookup) \ # .fetch(fields='line_type_intelligence') # if lti_info.valid and lti_info.line_type_intelligence: # print(f"回線種別 (LTI): {lti_info.line_type_intelligence.get('type')}") # print(f"キャリア名 (LTI): {lti_info.line_type_intelligence.get('carrier_name')}") # print(f"エラーコード (LTI): {lti_info.line_type_intelligence.get('error_code')}") # elif not lti_info.valid: # print(f"無効な番号です。エラー: {lti_info.validation_errors}") # else: # print("Line Type Intelligenceを取得できませんでした。")
except TwilioRestException as e: # 特に番号が見つからない場合 (HTTP 404) など if e.status == 404: print(f"電話番号 {phone_number_to_lookup} が見つかりませんでした。") else: print(f"Lookup APIの実行中にエラーが発生しました: {e}")

Lookup API v2 では、`line_type_intelligence` や `caller_name` など、さらに詳細な情報を取得するためのデータパッケージが用意されています。詳細はLookup v2 APIドキュメントを参照してください。

Twilio Verify APIは、SMS、音声通話、メール、WhatsAppなどを利用して、ユーザーの電話番号やメールアドレスを簡単に認証するための機能を提供します。主に二要素認証 (2FA) やワンタイムパスワード (OTP) の実装に使われます。

Verify APIを利用するには、まずTwilioコンソールまたはAPIで「Verifyサービス」を作成する必要があります。このサービスには、認証コードの桁数、有効期間、使用するチャネル（SMS, Voiceなど）などの設定が含まれます。

Pythonライブラリでの基本的な使い方は以下の流れになります。

1. Verifyサービスを作成する (初回のみ、またはAPI経由で動的に)。
2. client.verify.v2.services('サービスSID').verifications.create() を使って、指定した電話番号（またはメールアドレス）とチャネル（’sms’, ‘call’, ‘email’, ‘whatsapp’など）で認証コードの送信を開始する。
3. ユーザーが受け取った認証コードを入力する。
4. client.verify.v2.services('サービスSID').verification_checks.create() を使って、ユーザーが入力したコードが正しいか検証する。

以下は、SMSを使って電話番号認証を行うコード例です。

import os
from twilio.rest import Client
from twilio.base.exceptions import TwilioRestException
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
auth_token = os.environ["TWILIO_AUTH_TOKEN"]
verify_service_sid = os.environ["TWILIO_VERIFY_SERVICE_SID"] # 事前に作成したVerifyサービスのSID
client = Client(account_sid, auth_token)
phone_number_to_verify = "+819012345678" # 認証したい電話番号
# --- ステップ1: 認証コードの送信 ---
try: verification = client.verify.v2.services(verify_service_sid) \ .verifications \ .create(to=phone_number_to_verify, channel='sms') # channel='call' なども可能 print(f"認証コードを {phone_number_to_verify} にSMSで送信しました。") print(f"Verification SID: {verification.sid}") print(f"ステータス: {verification.status}") # 'pending' になるはず
except TwilioRestException as e: print(f"認証コードの送信に失敗しました: {e}") exit() # エラーが発生したら終了
# --- ステップ2: ユーザーからのコード入力を待つ ---
# 実際にはWebアプリケーションなどでユーザーに入力させる
user_entered_code = input("受信した認証コードを入力してください: ")
# --- ステップ3: 認証コードの検証 ---
try: verification_check = client.verify.v2.services(verify_service_sid) \ .verification_checks \ .create(to=phone_number_to_verify, code=user_entered_code) print(f"\n認証コードの検証結果:") print(f"検証ステータス: {verification_check.status}") # 'approved' または 'pending' (不正解の場合) print(f"有効か: {verification_check.valid}") # True または False if verification_check.valid: print(" 認証に成功しました！") else: print(" 認証に失敗しました。コードが間違っているか、有効期限が切れています。")
except TwilioRestException as e: print(f"認証コードの検証中にエラーが発生しました: {e}")

Verify APIの良い点は、Twilioが最適な送信ルートを選択してくれるため、開発者が電話番号を購入したり、複雑な配信ロジックを組んだりする必要がないことです。 多言語対応やPasskeys、TOTP（認証アプリ）連携など、さらに高度な機能も提供されています。詳細はVerify APIドキュメントを確認してください。