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ドキュメントを確認してください。