使い方ガイドに戻る

開発者向け

公開 API と配信 — Webhook の使い方

お客様のシステムから、SMS・オートコール・FAX の一斉配信、クリックトゥコール、通話履歴の取得、 SIPプロファイルと発信プレフィックスの管理を自動化できます。配信結果や受信 FAX は Webhook で受け取れます。 本番の live とサンドボックスの test の 2 環境があり、 test ではメッセージが送信されず、料金も発生しません。

ベース URL: https://hub.naruko.app/api/public/v1

1

API キーを発行する

コンソールの「共通 → API キー」でキーを発行します。サンドボックスのキーは nrk_test_…、本番のキーは nrk_live_… で始まります。まずは test から始めるのがおすすめです。 このページで説明するすべての API を、同じキーで利用できます。

API キー画面を開く

  • 平文キーは発行時に一度だけ表示されます。あとから再表示はできないため、紛失した場合は再生成で作り直します。
  • キーは無効化と再生成ができます。漏えい時は再生成で、今までのキーを即座に使えなくしてください。
  • test キーは実際には送信されず、課金もされません。登録した宛先・ジョブ・Webhook も本番のデータと分離されます。
  • 権限を Read Only にできます。配信の作成や登録を拒否し、参照だけを許可します。
  • 使える機能を選べます。選ばなかった機能を呼ぶと 403 になります。どの API がどの機能かは下の表のとおりです。
  • 扱える範囲をキャンペーン・電話番号で限定できます。たとえば 1 つのキャンペーンを選ぶと、そのキャンペーンの通話履歴だけを読めるキーになります。
  • 発行したあとでも機能・権限・範囲を変更できます。キーの値は変わらないので、外部システム側の設定を変える必要はありません。
  • すでに発行済みのキーは、これまでどおりすべての API を利用できます。

範囲の限定は、通話履歴・受信 FAX・配信・電話発信だけに働きます。 ほかの機能は、キャンペーンや電話番号を選んでも組織全体を扱えます。

機能使用可能な API扱える範囲
通話履歴/calls・/phonenumbers/{id}/callsキャンペーン・電話番号に限定できる
受信 FAX/fax-receiptsキャンペーン・電話番号に限定できる
配信/delivery-jobs・/media・/sender-numbers・/sms-senders・/openai-realtime/{id}/test-callキャンペーン・電話番号に限定できる
連絡先/contacts・/contact-lists・/opt-outs組織全体
電話発信/click-to-callキャンペーン・電話番号に限定できる
キャンペーン設定/campaigns・/phonenumbers組織全体
OpenAI 連携設定/openai-realtime。テスト発信だけは配信です組織全体
PBX 接続/sip-profiles・/caller-id-prefixes組織全体
API キー画面。ラベルと環境(サンドボックス / 本番)を選んで発行し、発行済みキーの無効化・再生成ができる
API キー画面
2

認証

各リクエストに API キーを付けます。Authorization: Bearer <key> を推奨、代替として X-Api-Key: <key> も使えます。

curl https://hub.naruko.app/api/public/v1/me \
  -H "Authorization: Bearer nrk_test_xxxxxxxx"
# {"account":{"id":1,"name":"…","status":"active","plan":null},"environment":"test"}
  • キーが未提示・無効・期限切れのいずれかのとき、401 を返します。
  • レート制限は API キーごとに 1 分あたり 180 リクエストです。超過すると 429 と Retry-After / X-RateLimit-* を返すので、Retry-After 秒待って再試行します。
3

主要エンドポイント

すべて https://hub.naruko.app/api/public/v1 配下です。 「使える機能」は、API キーを発行するときに選ぶ機能です。選ばなかった機能の API を呼ぶと 403 になります。

メソッドパス使える機能用途
GET/meどのキーでも疎通確認。account と environment を返します
POST/media配信原稿のアップロード。media_id を返します
POST/media/cover-sheet配信FAX 送付状の作成。media_id を返します
GET/contacts連絡先宛先の一覧・検索。q は部分一致、phone・external_id・email は完全一致です
POST/contacts連絡先宛先の登録。id を返します
GET/contacts/{id}連絡先宛先 1 件
PUT/contacts/{id}連絡先宛先の更新。送った項目だけが変わります
DELETE/contacts/{id}連絡先宛先の削除。一覧と配信の対象から外れます
GET/opt-outs連絡先配信停止電話番号の一覧。削除した宛先の電話番号も含みます
POST/opt-outs連絡先電話番号を配信停止にする
DELETE/opt-outs/{phone}連絡先電話番号の配信停止を解除する
GET/contact-lists連絡先宛先リストの一覧
POST/contact-lists連絡先宛先リストの作成
DELETE/contact-lists/{id}連絡先宛先リストの削除。宛先そのものは削除されません
POST/contact-lists/{id}/members連絡先宛先リストへ宛先を追加します。追加済みの宛先は無視します
DELETE/contact-lists/{id}/members/{contactId}連絡先宛先リストから宛先を取り除きます
GET/sender-numbers配信発信元電話番号の一覧。キャンペーンに割り当て済みのものを返します
GET/sms-senders配信SMS の発信元の一覧。承認済みのものを返します
GET/campaignsキャンペーン設定キャンペーンの一覧。割り当て済みの発信元電話番号も返します
POST/campaignsキャンペーン設定キャンペーンの作成
DELETE/campaigns/{id}キャンペーン設定キャンペーンの削除。割り当てていた電話番号は未割当に戻ります
PUT/campaigns/{id}/channelsキャンペーン設定同時発信数の割当。購入済みの本数が上限です
POST/campaigns/{id}/phonenumbersキャンペーン設定購入済みの電話番号をキャンペーンへ割り当てます
DELETE/campaigns/{id}/phonenumbers/{phonenumber}キャンペーン設定電話番号の割当を解除します
PUT/campaigns/{id}/default-senderキャンペーン設定既定の発信元を決めます
PUT/campaigns/{id}/send-windowキャンペーン設定送信可能時間帯の上書き
PUT/campaigns/{id}/post-call-notificationキャンペーン設定通話後の通知の設定
PUT/campaigns/{id}/ring-secondsキャンペーン設定オートコールの呼び出し秒数の既定
PUT/campaigns/{id}/tts-genderキャンペーン設定オートコールの読み上げの声の既定
PUT/campaigns/{id}/retryキャンペーン設定失敗時の再送の回数と間隔の既定
PUT/campaigns/{id}/realtime-amdキャンペーン設定AI と会話する自動発信の留守番電話の判定の既定
GET/campaigns/{id}/phonenumbers/{phonenumber}/incomingキャンペーン設定キャンペーンの電話番号の、現在の着信の動作
PUT/campaigns/{id}/phonenumbers/{phonenumber}/incomingキャンペーン設定キャンペーンの電話番号の着信の動作を切り替えます
GET/phonenumbers/{id}/incoming電話番号設定キャンペーンに属さない電話番号の、現在の着信の動作
PUT/phonenumbers/{id}/incoming電話番号設定キャンペーンに属さない電話番号の着信の動作を切り替えます
GET/phonenumbers/{id}/assignment電話番号設定電話番号の、現在の用途と使い方
PUT/phonenumbers/{id}/assignment電話番号設定電話番号の用途を付け替えます。旧用途は外れます
GET/roomsルーム設定ルームの一覧。割り当て済みの電話番号とメンバーも返します
POST/roomsルーム設定ルームの作成
GET/rooms/{id}/incomingルーム設定ルームの、現在の着信の設定
PUT/rooms/{id}/incomingルーム設定ルームの着信方式・呼び出し時間・無応答時の動作を変更します
GET/phonenumbersキャンペーン設定購入済みの電話番号の一覧。未割当のものも返します
POST/delivery-jobs配信一斉配信の受付。SMS・オートコール・FAX・email に対応します
GET/delivery-jobs/{id}配信ジョブの状態取得
GET/delivery-jobs/{id}/deliveries配信宛先ごとの配信結果。各行に contact_id・to_address・status・result_code が入ります
GET/delivery-jobs/{id}/stats配信ジョブの集計。到達率と失敗率を返します
POST/delivery-jobs/{id}/cancel配信ジョブのキャンセル
POST/delivery-jobs/{id}/reschedule配信予約日時の変更。予約中のジョブだけ変更できます
GET/fax-receipts受信 FAX受信 FAX の一覧。新しい順に返します
GET/fax-receipts/{id}受信 FAX受信 FAX 1 件
GET/fax-receipts/{id}/content受信 FAX受信 FAX の PDF 本文。期限はありません
GET/calls通話履歴通話履歴の一覧。新しい順に返します
GET/calls/{uniqueid}通話履歴通話 1 件
GET/phonenumbers/{id}/calls通話履歴1 つの電話番号の通話の一覧。キャンペーンに属さない電話番号も対象です
GET/openai-realtimeOpenAI 連携設定リアルタイムAI連携の一覧。API キーとシークレットは返しません
POST/openai-realtimeOpenAI 連携設定連携の作成
PATCH/openai-realtime/{id}OpenAI 連携設定連携の更新。送信した項目にだけ適用されます
DELETE/openai-realtime/{id}OpenAI 連携設定連携の削除。使っている電話番号があるときは confirm が要ります
POST/openai-realtime/{id}/register-webhookOpenAI 連携設定Webhook URL をお使いの OpenAI プロジェクトへ登録します
GET/openai-realtime/{id}/connection-checkOpenAI 連携設定設定がそろっているかを項目ごとに確認します
GET/openai-realtime/{id}/errorsOpenAI 連携設定最近のエラーと件数。監視に使えます
POST/openai-realtime/{id}/inbound-tokenOpenAI 連携設定着信トークンの再生成。新しい値を返します
POST/openai-realtime/{id}/test-call配信テスト発信。通話料が発生します
POST/click-to-call電話発信クリックトゥコール。担当者を鳴らしてから顧客へつなぎます
POST/sandbox/webhook-eventsどのキーでもサンドボックスでダミー Webhook を送信。test キー専用です
4

配信ジョブで一斉送信する

コンソールの 連絡先 で作成した宛先リスト、登録済みの宛先、電話番号のどれかを指定して送ります。受付は 202 Accepted で job_id を返し、実送信は非同期です。 Idempotency-Key を付けると、リトライ時の二重受付を防げます。キーは 48 時間有効で、同じキーで内容が違うリクエストは 409 になります。

curl -X POST https://hub.naruko.app/api/public/v1/delivery-jobs \
  -H "Authorization: Bearer nrk_test_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
        "send_type": "sms",
        "content": { "text": "こんにちは" },
        "target_spec": { "list_id": 123 }
      }'
# 202 {"job_id":45,"status":"queued"}
項目指定できる値
send_typesms / autocall / fax / email
target_spec.list_id宛先リストへ送る
target_spec.contact_ids宛先を 1 件ずつ指定して送る
target_spec.phones電話番号を直接指定して送る。同じ電話番号の宛先があればそれを使い、無ければ登録します。test キーでも登録されます
campaign_id配信ジョブを入れるキャンペーン。省略すると、発信元を割り当てたキャンペーンに入り、どちらも無ければ組織の既定のキャンペーンに入ります
content.sms_sender_idSMS の発信元。/sms-senders の id。省略したときの扱いは 配信の設定とキャンペーンの既定 にあります。0 を指定すると、キャンペーンの既定があっても共通の電話番号から送信します。共通の電話番号は SMS の発信元を選ぶ にあります
status意味
sent送信を実行した
delivered到達を確認した。SMS は送信からおおむね数分以内に確定します
failed1 回の試行が失敗した
dead失敗が確定した。再送の上限に達したとき、または SMS が届かなかったときです

status は Webhook で受け取るのが基本です。 お支払い方法が未登録のとき、sms / autocall / fax は 402 と payment_method_required を返します。

電話番号を指定して SMS を 1 通ずつ送る

予約の確認のように 1 通ずつ送るときは、target_spec.phones に電話番号を指定します。宛先を先に登録する必要はありません。

curl -X POST https://hub.naruko.app/api/public/v1/delivery-jobs \
  -H "Authorization: Bearer nrk_test_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reservation-20261120-0001" \
  -d '{
        "send_type": "sms",
        "content": { "text": "11/20 15:00 のご予約を承りました。", "sms_sender_id": 3 },
        "target_spec": { "phones": ["09000000000"] }
      }'
# 202 {"job_id":46,"status":"queued","contacts":[{"phone":"09000000000","phone_e164":"+819000000000","contact_id":456}]}
  • 同じ電話番号へ何度送っても、宛先の登録は 1 件のままです。初めて送る電話番号は宛先として自動で登録され、2 回目からはその宛先を使います。
  • 応答の contacts に、指定した電話番号ごとの宛先の contact_id を返します。phone は送った値のままです。Webhook の data にも contact_id が入ります。
  • 配信停止にした宛先の電話番号を指定しても、送信しません。配信結果の status は suppressed、result_code は opt_out になり、Webhook は送信しません。
  • 1 回のリクエストで指定できる電話番号は 1,000 件までです。それより多いときは宛先リストを使ってください。
  • test キーでも宛先は登録されます。実際の送信と課金は行われません。
  • SMS の本文は 660 文字までです。超えると 422 になります。全角と半角は、どちらも 1 文字と数えます。𠮷 のような一部の漢字は 2 文字と数えます。660 文字までの長文は分割されず、受け取った方の携帯に 1 件の SMS として表示されます。
  • 絵文字は使用できません。😀 や ✅ のように携帯で絵文字として表示される文字が含まれていると 422 になります。☎ や ♪ などの記号と、𠮷 のような漢字は送れます。iPhone などで ☎ が絵文字として入力された場合は、記号に直して送ります。
  • 受け取った方が SMS に返信しても、その返信は受け取れません。

SMS の配信結果

宛先の電話番号が利用されていなくても、配信ジョブの作成は 202 になり、送信は sent になります。届いたかどうかは数分後に確定し、 delivered か dead になります。 Webhook は delivery.sent のあとに delivery.delivered か delivery.dead が届きます。

status状態result_code
queued配信ジョブを作成した直後null
sending配信事業者へ送信しているnull
sent配信事業者が受け付けた。届いたかどうかは数分後に決まる0000
delivered宛先の携帯電話に届いた0001
dead届かなかった。到達の知らせが 48 時間以内に届かなかった場合も dead になる0002・0004・0034・sms_dr_expired

result_code の 4 桁の数字は配信事業者が返す値、英字は送信しなかった理由か送信の失敗を表す値です。 dead のときは、到達ログの error_detail に届かなかった理由が入ります。

result_codestatus意味
0000sent配信事業者が受け付けた
0001delivered届いた
0002dead宛先の携帯電話に届かなかった。電源が入っていない・圏外・SMS の受信を拒否している など
0004dead宛先の電話番号は利用されていない
0034dead配信が取り消された
sms_send_failedfailed・dead配信事業者へ送信できなかった。再送の上限に達すると dead になります
sms_unsendabledead本文か宛先が無いため送信していない
sms_dr_expireddead到達の知らせが 48 時間以内に届かなかった。届いたかどうかは分からないため、送信し直す前に相手に届いているかを確認してください
opt_outsuppressed配信停止の宛先のため送信していない
no_addresssuppressed宛先に SMS の電話番号が無いため送信していない
sandboxdeliveredtest キーのため送信していない。到達として扱う

SMS の発信元を選ぶ

content.sms_sender_id を省略し、キャンペーンにも既定の発信元が無ければ、共通の電話番号 050-5050-0072 から送ります。SoftBank の携帯では、携帯会社の仕様により 247450 と表示されます。承認済みの発信元から送るときは、一覧で id を確かめて指定します。 発信元に登録できるのは、代表電話などの固定電話・0120・0800・050 の電話番号です。携帯電話番号と英字の名前は登録できません。

curl https://hub.naruko.app/api/public/v1/sms-senders \
  -H "Authorization: Bearer nrk_test_xxxxxxxx"
# 200 {"data":[{"id":3,"number":"0312345678","campaign_id":null}]}

電話番号の表記

  • 日本の電話番号は、0 から始まる表記で返します。配信結果の一覧の to_address と Webhook の to が対象です。コンソールから書き出す配信結果の CSV も同じ表記です。
  • 配信結果の一覧は、phone_format=e164 を指定すると +81 から始まる表記で返します。
  • 宛先は、0 から始まる表記の phone・phone_call・phone_sms・fax と、+81 から始まる表記の phone_e164・phone_call_e164・phone_sms_e164・fax_e164 の両方を返します。配信停止電話番号も phone と phone_e164 を返します。
  • 国外の電話番号とメールアドレスは、どの指定でも変えません。

q は名前・電話番号・メールの部分一致です。お手元の記録から宛先を 1 件に決めるときは、完全一致の指定を使います。複数を指定した場合は、すべてに一致する宛先を返します。削除した宛先は含めません。

指定照合
phone電話番号の完全一致。ハイフン・空白・+81 の違いは同じ電話番号として扱います
phone_typecall・sms・fax のいずれか。phone と一緒に指定します。省略するとすべての電話番号と照合します
external_id完全一致
email完全一致。大文字と小文字は区別しません

phone_type に call か sms を指定すると、その種別の電話番号が登録されていない宛先は、登録時の phone で照合します。配信ジョブで target_spec.phones を指定したときと同じ宛先が見つかります。

curl "https://hub.naruko.app/api/public/v1/contacts?phone=03-1234-5678&phone_type=call" \
  -H "Authorization: Bearer nrk_test_xxxxxxxx"
# 200 {"data":[{"id":456,"phone_call_e164":"+81312345678",...}],...}

宛先を更新・削除する

更新では、送った項目だけが変わります。値を消すときは null を送ります。削除した宛先は、一覧と配信の対象から外れます。

配信停止の宛先を削除しても、その電話番号は配信停止電話番号に残り、送信しません。同じ電話番号で宛先を登録し直した場合も、配信停止になります。

# 名前だけを変える。電話番号と配信停止はそのまま
curl -X PUT https://hub.naruko.app/api/public/v1/contacts/456 \
  -H "Authorization: Bearer nrk_test_xxxxxxxx" -H "Content-Type: application/json" \
  -d '{"name":"山田 太郎"}'

# 配信停止にする
curl -X PUT https://hub.naruko.app/api/public/v1/contacts/456 \
  -H "Authorization: Bearer nrk_test_xxxxxxxx" -H "Content-Type: application/json" \
  -d '{"opt_out":true}'

# 削除する
curl -X DELETE https://hub.naruko.app/api/public/v1/contacts/456 \
  -H "Authorization: Bearer nrk_test_xxxxxxxx"

配信停止電話番号

配信停止の宛先が持つ電話番号です。削除した宛先の電話番号も含みます。どの宛先を指定しても、この電話番号へは送信しません。

  • 登録すると、同じ電話番号の宛先をすべて配信停止にします。宛先が無ければ、配信停止の宛先を登録します。
  • 解除すると、同じ電話番号を持つ宛先の配信停止をすべて外します。削除した宛先も対象です。宛先がほかの電話番号も持つ場合は、その電話番号の配信停止も外れます。
  • 宛先の更新で opt_out を false にした場合も、同じ電話番号の削除した宛先の配信停止を外します。
# 一覧。phone で絞り込めます
curl "https://hub.naruko.app/api/public/v1/opt-outs?phone=03-1234-5678" \
  -H "Authorization: Bearer nrk_test_xxxxxxxx"
# 200 {"data":[{"phone_e164":"+81312345678","contact_ids":[456]}],...}

# 配信停止にする
curl -X POST https://hub.naruko.app/api/public/v1/opt-outs \
  -H "Authorization: Bearer nrk_test_xxxxxxxx" -H "Content-Type: application/json" \
  -d '{"phone":"03-1234-5678"}'
# 201 {"phone_e164":"+81312345678","contact_ids":[456],"created":false}

# 解除する
curl -X DELETE https://hub.naruko.app/api/public/v1/opt-outs/+81312345678 \
  -H "Authorization: Bearer nrk_test_xxxxxxxx"
# 200 {"phone_e164":"+81312345678","released_contacts":2}

送る前の準備

オートコールと FAX は、発信元電話番号をキャンペーンへ割り当て、同時発信数を決めてから送ります。 キャンペーン管理 と同じことを API でも行えます。電話番号と同時発信数の購入はコンソールで行ってください。

# 1. キャンペーンを作る
curl -X POST https://hub.naruko.app/api/public/v1/campaigns \
  -H "Authorization: Bearer $NARUKO_TODOKE_KEY" -H "Content-Type: application/json" \
  -d '{"name":"9 月キャンペーン"}'
# 201 {"campaign":{"id":12,...}}

# 2. 購入済みで、まだどこにも割り当てていない電話番号を探す
curl "https://hub.naruko.app/api/public/v1/phonenumbers?unassigned=1&kind=voice" \
  -H "Authorization: Bearer $NARUKO_TODOKE_KEY"

# 3. 電話番号を割り当てる。1 本目は既定の発信元になります
curl -X POST https://hub.naruko.app/api/public/v1/campaigns/12/phonenumbers \
  -H "Authorization: Bearer $NARUKO_TODOKE_KEY" -H "Content-Type: application/json" \
  -d '{"phonenumber_id":123}'

# 4. 同時発信数を割り当てる
curl -X PUT https://hub.naruko.app/api/public/v1/campaigns/12/channels \
  -H "Authorization: Bearer $NARUKO_TODOKE_KEY" -H "Content-Type: application/json" \
  -d '{"channels":2}'

購入済みの本数を全キャンペーンの合計が超える割当は 422 になります。

組織ごとに最初から用意してある「既定のキャンペーン」は、削除と送信可能時間帯の上書きができず、どちらも 422 になります。既定のキャンペーンの送信可能時間帯は、組織全体の送信可能時間帯を使います。「既定のキャンペーン」と同じ名前のキャンペーンは作れません。

配信の設定とキャンペーンの既定

下の設定は content で配信ごとに指定します。 省略するとキャンペーンの既定に従い、キャンペーンにも既定が無ければ表の「全体の既定」です。 範囲外・候補にない値は 422 になります。 キャンペーンの既定は表の API に値を送信して設定し、null で解除します。

content のキー指定できる値全体の既定キャンペーンの既定
retry_max送信に失敗したときに送信し直す回数。0〜5 の整数。オートコールは発信できなかったときのみ送信し直し、無応答・話中では送信し直しません2PUT /campaigns/{id}/retry
retry_interval_minutes送信し直す間隔の分数。1〜60 の整数。SMS・FAX は回数に比例して間隔が延びますSMS・FAX は 5・オートコールは 1PUT /campaigns/{id}/retry
send_window送信可能時間帯。enabled・skip_holidays・days を PUT /campaigns/{id}/send-window と同じ形で指定します。SMS・オートコール・FAX で使えます組織の送信可能時間帯PUT /campaigns/{id}/send-window
sms_sender_idSMS の発信元。/sms-senders の id。キャンペーンの既定は、キャンペーンに割り当てた承認済みの発信元から選びます共通の電話番号PUT /campaigns/{id}/default-sender に sms_sender_id
ring_seconds相手を呼び出す秒数。10〜60 の整数。経過すると発信を打ち切り、result_code が no_answer になります30PUT /campaigns/{id}/ring-seconds
tts_gender読み上げの声。female か male。本文・プッシュ応答・電話アンケートの読み上げに使いますfemalePUT /campaigns/{id}/tts-gender
realtime_amdAI と会話する自動発信の留守番電話の判定。true か falsefalsePUT /campaigns/{id}/realtime-amd
curl -X POST https://hub.naruko.app/api/public/v1/delivery-jobs \
  -H "Authorization: Bearer nrk_test_xxxxxxxx" -H "Content-Type: application/json" \
  -d '{
        "send_type": "autocall",
        "content": {
          "text": "ご予約の確認です。",
          "sender_phonenumber_id": 123,
          "ring_seconds": 45,
          "tts_gender": "male"
        },
        "target_spec": { "contact_ids": [456] }
      }'

curl -X PUT https://hub.naruko.app/api/public/v1/campaigns/12/tts-gender \
  -H "Authorization: Bearer nrk_test_xxxxxxxx" -H "Content-Type: application/json" \
  -d '{"tts_gender": "male"}'

AI と会話する自動発信

content.mode に realtime を指定すると、読み上げではなく AI が応答します。 話す内容は リアルタイムAI連携 に設定した応答の指示で決まるため、読み上げ本文も音声ファイルも要りません。

curl -X POST https://hub.naruko.app/api/public/v1/delivery-jobs \
  -H "Authorization: Bearer $NARUKO_TODOKE_KEY" -H "Content-Type: application/json" \
  -d '{
        "send_type": "autocall",
        "content": {
          "mode": "realtime",
          "realtime_integration_id": 7,
          "realtime_amd": true,
          "sender_phonenumber_id": 123
        },
        "target_spec": { "contact_ids": [456] }
      }'
項目意味
realtime_integration_idどの連携で会話させるか。指定が無いと 422 になります
realtime_amd留守番電話の判定。有効にすると、人が応答したと判定できたときだけ AI へつなぎます。判定には数秒を要し、その間は無音になります
sender_phonenumber_id発信元電話番号。電話番号ごとの応答の指示もこれで決まります

通話後の通知

オートコールの通話が終わったあと、結果に応じて SMS と Webhook で本文を送信します。 content.post_call_notification を省略するとキャンペーンの設定を使い、 null を指定するとこの配信では送信しません。 キャンペーンの設定は PUT /campaigns/{id}/post-call-notification で同じ形を送信します。

curl -X POST https://hub.naruko.app/api/public/v1/delivery-jobs \
  -H "Authorization: Bearer nrk_test_xxxxxxxx" -H "Content-Type: application/json" \
  -d '{
        "send_type": "autocall",
        "content": {
          "text": "ご予約の確認です。ご予約どおりなら 1 を、変更なら 2 を押してください。",
          "ivr": { … },
          "sender_phonenumber_id": 123,
          "post_call_notification": {
            "messages": {
              "answered": "ご予約の確認のお電話でした。",
              "unanswered": "ご予約の確認でお電話しました。",
              "dtmf": { "1": "ご予約を確定しました。", "2": "変更はこちらから: https://example.com/r" }
            },
            "sms": { "sms_sender_id": 12 },
            "webhook": { "endpoint_id": 34 }
          }
        },
        "target_spec": { "contact_ids": [456] }
      }'
項目送信するとき
messages.answered応答。本文を決めていない回答のときも、この本文を送信します
messages.unanswered無応答。応答が無い・話中・発信に失敗のとき
messages.dtmf回答。相手が押した数字ごとの本文で、最初に押した数字で決まります
sms宛先の SMS 用の電話番号へ送信します。料金は通常の SMS と同じです
webhookrequest_timing が post_call.notification の通知を送信します。組み立てJSON形式では {{ message }} に本文が入ります

OpenAI 連携設定

OpenAI のプロジェクト ID や API キーを API から設定できます。 使える機能で OpenAI 連携設定 を選んだキーが必要です。 更新は送信した項目にだけ適用されます。

# 連携の一覧。API キーと Webhook シークレットは返りません
curl https://hub.naruko.app/api/public/v1/openai-realtime \
  -H "Authorization: Bearer $NARUKO_TODOKE_KEY" -H "Accept: application/json"

# プロジェクト ID を変更する
curl -X PATCH https://hub.naruko.app/api/public/v1/openai-realtime/7 \
  -H "Authorization: Bearer $NARUKO_TODOKE_KEY" -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"openai_project_id":"proj_xxxxxxxxxxxx"}'

# Webhook URL をお使いの OpenAI プロジェクトへ登録する
curl -X POST https://hub.naruko.app/api/public/v1/openai-realtime/7/register-webhook \
  -H "Authorization: Bearer $NARUKO_TODOKE_KEY" -H "Accept: application/json"

# 設定がそろっているかを項目ごとに確認する。電話は発生しません
curl https://hub.naruko.app/api/public/v1/openai-realtime/7/connection-check \
  -H "Authorization: Bearer $NARUKO_TODOKE_KEY" -H "Accept: application/json"

# 1 件だけ発信して、AI と会話できるかを確かめる
curl -X POST https://hub.naruko.app/api/public/v1/openai-realtime/7/test-call \
  -H "Authorization: Bearer $NARUKO_TODOKE_KEY" -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"callee":"09000000000"}'

Webhook URL の登録は何度でも実行できます。同じ URL がすでに登録されている場合は、登録内容を変更しません。 既に他の URL の登録がある場合は、既存の登録は変更されず、この Webhook URL が追加登録されます。

テスト発信は実際に電話を発信するため、通話料が発生し、同時発信数の枠を 1 ch 使います。 使える機能で 配信 を選んだキーが必要です。結果は配信ジョブとして確認できます。 発信元はこの連携を使っていてキャンペーンに割り当て済みの電話番号から選ばれ、候補が複数あるときは sender_phonenumber_id で指定します。

openai_api_key と openai_webhook_secret は設定できますが、取得はできません。 設定済みかどうかは config.has_api_key で判断します。

クリックトゥコール

CRM や Excel マクロから「担当者 → 顧客」の 2 レグ発信を起こせます。先に担当者を鳴らし、応答したあとで顧客へダイヤルしてつなぎます。 発信元電話番号は from_phonenumber_id で指定します。お使いの組織が保有する電話番号だけを指定できます。

curl -X POST https://hub.naruko.app/api/public/v1/click-to-call \
  -H "Authorization: Bearer $NARUKO_TODOKE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from_phonenumber_id": 123, "agent": "2001", "callee": "0312349003", "caller_id": "0312340000"}'
# 202 {"accepted":true,"call_id":"c2c_XXXXXXXX"}
5

FAX を API で送受信する

先に用意するもの

用意するもの内容
キャンペーンと電話番号送信の発信元になり、受信もこの電話番号で受けます
配信チャネル⚠️ 割り当てが 0 のキャンペーンでは FAX を送信できません。同時に送れる数も割り当てた数までです
API キー送信は test でも試せますが、受信は live のみです

宛先と発信元を用意する

配信ジョブは宛先の IDと発信元電話番号の IDで指定します。 どちらも API で引けます。

# 宛先を登録する。external_id はお使いのシステムの顧客 ID と突き合わせるために使えます
curl -X POST https://hub.naruko.app/api/public/v1/contacts \
  -H "Authorization: Bearer $NARUKO_TODOKE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"山田商店","fax":"0312345678","external_id":"cust-001"}'
# 201 {"contact":{"id":789,"fax_e164":"+81312345678", ...}}

# 発信元電話番号を引く。FAX 用でキャンペーンに割り当て済みのものが返ります
curl "https://hub.naruko.app/api/public/v1/sender-numbers?kind=fax" \
  -H "Authorization: Bearer $NARUKO_TODOKE_KEY"
# {"data":[{"id":456,"number":"0312345600","kind":"fax","campaign_id":12}]}

送る

① 原稿の PDF をアップロードして media_id をもらう → ② その ID を指定して配信ジョブを投げます。1 つの原稿を宛先リストへ一斉送信できます。

# ① 原稿の PDF をアップロードする。PDF のみ・最大 20MB
curl -X POST https://hub.naruko.app/api/public/v1/media \
  -H "Authorization: Bearer $NARUKO_TODOKE_KEY" \
  -F "file=@invoice.pdf"
# 201 {"media_id":123,"pages":2}

# ② FAX の配信ジョブを投げる
curl -X POST https://hub.naruko.app/api/public/v1/delivery-jobs \
  -H "Authorization: Bearer $NARUKO_TODOKE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "send_type": "fax",
        "content": { "media_id": 123, "sender_phonenumber_id": 456 },
        "target_spec": { "list_id": 45 }
      }'
# 202 {"job_id":67,"status":"queued"}
FAX だけの決まり内容
content.media_id原稿。必須です
content.sender_phonenumber_id発信元電話番号。必須です
宛先連絡先の FAX 番号。入っていない宛先は送信されません
原稿の形式PDF のみ・最大 20MB。送信用の形式への変換は Naruko 側で行います
同時に送れる数配信チャネルの割り当て数まで。割り当てが無いと 422 と todoke_channels_required を返します。⚠️ 超えた分は失敗にせず順番待ちになります
失敗した宛先既定で 2 回まで自動で再送します。回数と間隔は content.retry_max・content.retry_interval_minutes で変更できます。確定失敗は delivery.dead で通知されます

送付状を付けるときは POST /media/cover-sheet を使います。 本文の書類を document に入れて一緒に送ると 結合した 1 つの PDF になり、 media_id が返るので、そのまま配信ジョブへ渡せます。 ⚠️ 1 通あたりのページ上限を超えると 422 で返ります。

Webhook で受け取る

FAX のキャンペーンに割り当てた電話番号へ着信すると、fax.received が 登録した Webhook に届きます。

{
  "event": "fax.received",
  "data": {
    "fax_recv_id": 123,
    "campaign_id": 45,
    "campaign_name": "請求書送付キャンペーン",
    "caller_phonenumber": "+81312349001",
    "received_at": "2026-08-29T10:00:00+09:00",
    "download_url": "https://...",
    "fields": { "金額": "120,000", "請求書番号": null }
  }
}
  • 受信の通知は live のエンドポイントにだけ届きます。電話番号は実回線で、送信のような test / live の区別が無いためです。environment=test で登録した URL には届きません。
  • download_url は24 時間で期限切れになります。受け取ったあとすぐに取得して、お客様のシステム側に保存してください。取得に失敗したときは null で届きます。
  • 着信元電話番号は一部を伏字にせず、そのまま渡します。コンソールの表示とは異なります。

受信した FAX から項目を読み取る

FAX の電話番号ごとに読み取る項目の名前を登録すると、 受信した PDF から AI がその項目を読み取り、fields に入れて返します。 設定は「共通」→「電話番号」の、その電話番号のカードの中です。読み取る項目と、読み取りに使う OpenAI のキーを同じ場所で登録します。

  • 項目の名前だけを登録します。用紙のどこに書かれているかは指定しません。1 つの電話番号につき 10 項目までです。
  • 読み取れなかった項目は null で返します。当て推量の値は入れません。
  • 項目を登録していない電話番号では、fields は空です。
  • AI の利用料はお客様の OpenAI アカウントへ直接請求されます。読み取りの費用は請求しません。
  • 読み取った項目は「FAX履歴」の画面でも確認できます。
電話番号の設定で、読み取る項目の名前と、読み取りに使う OpenAI のキーを登録する欄
「共通」→「電話番号」で、読み取る項目と OpenAI のキーを登録します
FAX履歴の画面で、受信した FAX から読み取った項目が並ぶ行
「FAX履歴」の画面でも、読み取った項目を確認できます

API で引き直す

受信サーバーが停止していたなどで Webhook を取りこぼしたときは、 GET /fax-receipts でいつでも一覧を引き直せます。 項目名は fax.received と同じです。

curl https://hub.naruko.app/api/public/v1/fax-receipts?since=2026-09-01T00%3A00%3A00%2B09%3A00 \
  -H "Authorization: Bearer nrk_live_..."

# PDF は期限を気にせずこちらから取得できます
curl https://hub.naruko.app/api/public/v1/fax-receipts/123/content \
  -H "Authorization: Bearer nrk_live_..." -o fax.pdf
  • 絞り込みは campaign_id / since / until / per_page です。1 ページの件数は最大 100 です。
  • 日時は URL エンコードしてください。+09:00 の + はそのままだと空白として解釈されます。
  • 返すのはキャンペーンに割り当てた電話番号の受信だけです。Naruko Chat のルームに届いた FAX は含みません。
  • test キーでは本番の受信を返しません。空の一覧になります。受信は live のみです。
  • 一覧の download_url は 24 時間で期限切れですが、/content は期限がありません。
6

通話の終了を確認する

キャンペーンに割り当てた電話番号の着信とオートコールの発信について、 いつ終わったか・応答したか・何秒話したかを API で確認できます。 direction で inbound / outbound に絞り込めます。

通話が終わったかは、通話 ID で引いて結果が返るかで判定します。 通話の記録は通話が終わった時点で書き込まれるため、通話中は 404 になります。

  • 返る行には calldate_end が必ず入っています。終了の判定には使えません。
  • 404 は、対象外の電話番号や存在しない通話 ID でも返ります。終了を待つために再試行を続けないでください。
  • 着信の終了をすぐに知るには、着信 Webhook の incoming_call_hangup を使います。API は、受け取れなかった通話を引き直すときに使います。

キャンペーンに属さない電話番号の通話は、電話番号を指定して /phonenumbers/{id}/calls で取得します。 行の形は同じで、direction はその電話番号から見た向きです。

1 つの通話が、複数の行に分かれることがあります。 同じ通話の行は、同じ uniqueid を持ちます。 例えば、AI が応答できず外線へ転送した通話は、次の 2 行になります。

行actionstagecall_status
AI へつないだ行realtime_ainullNO ANSWER
外線へ転送した行transferfallbackANSWERED

ルームのメンバーを順に呼び出したときも、呼び出しごとに 1 行になります。応答しなかった呼び出しも行として含まれます。 通話全体の結果は 1 行にまとめていません。行ごとの call_status で確かめてください。

# 期間で引く
curl "https://hub.naruko.app/api/public/v1/calls?since=2026-09-01T00%3A00%3A00%2B09%3A00" \
  -H "Authorization: Bearer nrk_live_..."

# 通話 ID で引く
curl https://hub.naruko.app/api/public/v1/calls/1700000000.42 \
  -H "Authorization: Bearer nrk_live_..."
# 電話番号を指定して引く
curl https://hub.naruko.app/api/public/v1/phonenumbers/34/calls \
  -H "Authorization: Bearer nrk_live_..."
{
  "data": [
    {
      "uniqueid": "1700000000.42",
      "direction": "outbound",
      "calldate": "2026-09-20T12:52:04+09:00",
      "calldate_answer": "2026-09-20T12:52:13+09:00",
      "calldate_end": "2026-09-20T12:53:00+09:00",
      "call_status": "ANSWERED",
      "caller_phonenumber": "0312340000",
      "callee_phonenumber": "0312349003",
      "call_duration": 47,
      "action": "transfer",
      "stage": "fallback",
      "campaign_id": 11,
      "campaign_name": "AI受付"
    },
    {
      "uniqueid": "1700000000.42",
      "direction": "inbound",
      "calldate": "2026-09-20T12:51:44+09:00",
      "calldate_answer": null,
      "calldate_end": "2026-09-20T12:52:04+09:00",
      "call_status": "NO ANSWER",
      "caller_phonenumber": "0312345678",
      "callee_phonenumber": "0312340000",
      "call_duration": 0,
      "action": "realtime_ai",
      "stage": null,
      "campaign_id": 11,
      "campaign_name": "AI受付"
    }
  ],
  "total": 2
}

action と stage

actionその行でしたこと
roomルームのメンバーを呼び出しました
extension内線を呼び出しました
outboundアプリ・電話機から外線へ発信しました
trunkお使いの PBX とトランクでつなぎました。発信か着信かは direction で分かります
transfer外線へ転送しました
ivrIVR の音声メニューで受けました
voicemail留守電で受けました
ai_agentAIエージェントへつなぎました
realtime_aiリアルタイムAI連携へつなぎました
autocallオートコールで発信しました
faxFAX を送信または受信しました。どちらかは direction で分かります
click_to_callクリックトゥコールで発信しました
busy話中を返しました
blocked着信を拒否しました
null上のどれにも当たらない行です
stage意味
fallback最初の動作で応答できず、次の動作へ進んだ行です。たとえば、AI が応答できずに外線へ転送した行や、ルームのメンバーが応答せずに留守電へ進んだ行です
null最初の動作の行です

call_status の値

値意味
ANSWERED応答して通話が成立しました。
NO ANSWER呼び出しましたが、応答がないまま終わりました。
BUSY話中を返しました。AI 応答やルームへの着信で応答が間に合わなかったとき、チャネルが足りなかったときもこの値になります。
FAILED接続できないまま終わりました。

絞り込み

パラメータ説明
uniqueid1 つの通話に絞り込みます。着信 Webhook で受け取った uniqueid をそのまま渡せます。
direction通話の向きで絞り込みます。inbound か outbound を指定します。
campaign_idキャンペーンで絞り込みます。
sinceこの時刻以降に始まった通話。日時は URL エンコードしてください。+09:00 の + は、そのままだと空白として解釈されます。
untilこの時刻までに始まった通話。書き方は since と同じです。
per_page1 ページの件数。1 から 100 まで指定でき、既定は 50 です。
  • 転送の行は、着信を受けた電話番号が caller_phonenumber、転送先が callee_phonenumber になり、direction は outbound です。
  • 返すのはキャンペーンに割り当てた電話番号の発着信だけです。Naruko Chat のルーム通話や内線通話は含みません。
  • test キーでは本番の通話を返しません。空の一覧を返します。
7

着信を切り替える

電話番号に着信したときの動作と、電話番号の用途を、API で取得・変更できます。 お使いのシステムに障害が発生した際に、AI による応答から担当者への転送へ切り替える用途を想定しています。 設定の保存と入力の検証は、管理画面と同じ処理で行います。

キャンペーンの電話番号は /campaigns/{id}/phonenumbers/{phonenumber}/incoming、 それ以外の電話番号は /phonenumbers/{id}/incoming を使用します。 誤った API を使用した場合は 409 を返し、使用すべき API をお知らせします。

# 1. 現状の設定を確認し、保存する
curl https://hub.naruko.app/api/public/v1/campaigns/12/phonenumbers/34/incoming \
  -H "Authorization: Bearer nrk_live_..."
# {"data":{"phonenumber_id":34,"action":"realtime_ai","realtime_ai_target":"i3",...}}

# 2. 外線転送へ切り替える
curl -X PUT https://hub.naruko.app/api/public/v1/campaigns/12/phonenumbers/34/incoming \
  -H "Authorization: Bearer nrk_live_..." -H "Content-Type: application/json" \
  -d '{"action":"transfer","transfer_to":"0312345678","transfer_timeout":30}'

# 3. 復旧後、1 で取得した値を送信して元の設定に戻す
curl -X PUT https://hub.naruko.app/api/public/v1/campaigns/12/phonenumbers/34/incoming \
  -H "Authorization: Bearer nrk_live_..." -H "Content-Type: application/json" \
  -d '{"action":"realtime_ai","realtime_ai_target":"i3"}'

取得時の項目名は、変更時に送信する項目名と同じです。取得した値をそのまま送信すると、元の設定に戻せます。

action の値

action一緒に送る値動作
busyなし話中で切断します
transfertransfer_to・transfer_timeout外線へ転送します。呼び出しの待ち時間は 5〜120 秒で指定します
roomroom_idルームで着信を受けます
ivrivr_idIVR で着信を受けます
realtime_airealtime_ai_targetリアルタイム応答。値は「i」に続けて連携の ID を指定します
trunktrunk_idトランクへ転送します
scheduleschedule着信スケジュールにより、営業時間内と時間外で動作を切り替えます

transfer と realtime_ai は、キャンペーンの電話番号でのみ選択できます。

用途を変更する

電話番号の割り当て先を、ルーム・トランク・キャンペーンの間で変更します。変更すると、元の割り当ては解除されます。 対象は組織が保有するすべての電話番号で、API キーには「電話番号設定」の機能が必要です。

curl -X PUT https://hub.naruko.app/api/public/v1/phonenumbers/34/assignment \
  -H "Authorization: Bearer nrk_live_..." -H "Content-Type: application/json" \
  -d '{"target":"room","target_id":5}'
# {"data":{"phonenumber_id":34,"number":"0312340001","target":"room","target_id":5,"usage":"voice"}}
項目説明
targetroom・trunk・campaign・none のいずれかを指定します。none はどこにも割り当てません
target_id割り当て先のルーム・トランク・キャンペーンの ID。none 以外の場合は必須です
usagevoice・fax・ivr のいずれかを指定します。省略した場合は、現在の使い方を維持します

ルームを作成する

オーナーとメンバーは、組織のユーザーのメールアドレスで指定します。API キーには「ルーム設定」の機能が必要です。 作成したルームへ電話番号を割り当てる場合は、上の「用途を変更する」を使います。

curl -X POST https://hub.naruko.app/api/public/v1/rooms \
  -H "Authorization: Bearer nrk_live_..." -H "Content-Type: application/json" \
  -d '{"name":"受付","owner_email":"owner@example.com","member_emails":["staff@example.com"]}'
# {"data":{"id":5,"name":"受付","type":"normal","phonenumber":null,"members":[...],"created_at":"..."}}
項目説明
nameルーム名
owner_emailオーナーにするユーザーのメールアドレス
member_emailsメンバーにするユーザーのメールアドレスの配列。省略できます

ルームの着信を設定する

電話番号を割り当てたルームで設定できます。指定した項目だけを変更します。音声再生で再生する音声は、ルーム管理の画面で登録します。

curl -X PUT https://hub.naruko.app/api/public/v1/rooms/5/incoming \
  -H "Authorization: Bearer nrk_live_..." -H "Content-Type: application/json" \
  -d '{"incoming_mode":"queue","ring_timeout":60,"no_answer_action":"voicemail"}'
項目説明
incoming_mode着信方式。queue は一斉呼び出し、queue_linear は順次呼び出し、confbridge は会議呼び出し、none は呼び出さない、announce は音声再生です
ring_timeout無応答時の動作へ切り替えるまでの秒数。5〜120
no_answer_action無応答時の動作。voicemail は留守電、ai_agent は AIエージェント、external_forward は外線転送、hangup は切断です
no_answer_forward_number外線転送の転送先の電話番号。external_forward の場合は必須です
8

Webhook を受け取る

コンソールの Webhook 画面 で通知先 URL と購読イベントを登録し、whsec_… で始まる署名鍵を控えます。 通知形式は JSON をそのまま送る raw のほか、Slack・Microsoft Teams・LINE 公式アカウント のテンプレートも選べるので、受信サーバーを用意しなくても既存のチャットツールへ通知できます。

組み立てJSON形式で送る

通知先の API が決まった形の JSON を求める場合は、通知形式に「組み立てJSON形式」を選び、送信する JSON を書きます。 文字列の中に {{ to }} のように書いた箇所へ、通知の値が入ります。 値だけを書いた箇所は、数値や null をそのまま入れます。 認証に使う値は、JSON の中に書くか、ヘッダーとして追加します。どちらも暗号化して保存します。 署名の X-Webhook-Signature ヘッダーは付けません。

{
  "id": "your-id",
  "password": "your-password",
  "phone_num": "{{ to }}",
  "text": "ご回答 {{ dtmf_response }} を受け付けました。",
  "job": "{{ job_id }}"
}
差し込める値使える通知内容
{{ event_id }}すべての通知通知の ID
{{ request_timing }}すべての通知通知の種類。delivery.delivered など
{{ created_at }}すべての通知通知の日時
{{ environment }}すべての通知live・test
{{ to }}配信の通知・通話後の通知宛先の電話番号
{{ status }}配信の通知・通話後の通知配信の状態。sent・delivered・failed・dead
{{ result_code }}配信の通知・通話後の通知結果のコード。SMS の値は「SMS の配信結果」の表のとおり
{{ dtmf_response }}配信の通知・通話後の通知オートコールで押された数字
{{ amd_detection }}配信の通知・通話後の通知オートコールの留守番電話の判定
{{ send_type }}配信の通知・通話後の通知sms・autocall・fax・email
{{ job_id }}配信の通知・通話後の通知配信ジョブの ID
{{ delivery_id }}配信の通知・通話後の通知宛先ごとの配信の ID
{{ contact_id }}配信の通知・通話後の通知宛先の ID
{{ fax_recv_id }}FAX の受信受信した FAX の ID
{{ campaign_id }}FAX の受信・リアルタイムAI連携の失敗キャンペーンの ID
{{ campaign_name }}FAX の受信キャンペーンの名前
{{ caller_phonenumber }}FAX の受信送信元電話番号
{{ received_at }}FAX の受信受信した日時
{{ download_url }}FAX の受信FAX の PDF をダウンロードする URL
{{ uniqueid }}リアルタイムAI連携の失敗通話の ID
{{ integration_id }}リアルタイムAI連携の失敗リアルタイムAI連携の ID
{{ integration_name }}リアルタイムAI連携の失敗リアルタイムAI連携の名前
{{ direction }}リアルタイムAI連携の失敗inbound・outbound
{{ stage }}リアルタイムAI連携の失敗どの段階で応答できなかったか
{{ reason_code }}リアルタイムAI連携の失敗理由のコード
{{ reason }}リアルタイムAI連携の失敗理由
{{ callee_phonenumber }}リアルタイムAI連携の失敗着信先電話番号。着信のときだけ
{{ fallback_action }}リアルタイムAI連携の失敗AI が応答できなかったあとに進んだ動作
{{ occurred_at }}リアルタイムAI連携の失敗発生した日時
{{ condition }}通話後の通知通話後の通知の条件。answered・unanswered・dtmf_1 など
{{ message }}通話後の通知通話後の通知の本文

イベント種別とペイロード

request_timing意味
delivery.sent送信を実行した。SMS では配信事業者が受け付けた段階で、届いたかどうかは delivery.delivered か delivery.dead で決まる
delivery.delivered到達を確認した
delivery.failed1 回の試行が失敗した
delivery.dead失敗が確定した
fax.receivedFAX を受信した
realtime.failedリアルタイム応答で AI が応答できなかった

raw で受け取る場合のペイロード例:

{
  "id": "evt_XXXXXXXX",
  "request_timing": "delivery.delivered",
  "created_at": "2026-07-06T09:00:00+09:00",
  "environment": "live",
  "data": {
    "delivery_id": 987,
    "job_id": 45,
    "contact_id": 456,
    "send_type": "sms",
    "to": "09000000000",
    "status": "delivered",
    "result_code": null
  }
}

data.to は日本の電話番号なら 0 から始まる形式で、国外の電話番号は + から始まります。 id を冪等キーにして二重処理を防いでください。2xx を返すと、この通知は送信済みになります。

署名の検証

raw には X-Webhook-Signature ヘッダが付きます。 署名対象は "{t の値}.{raw データ}" の HMAC-SHA256 を 16 進で表したものです。 ヘッダは t=<unix秒>,v1=<hex> の形式です。 検証は raw データのまま行ってください。

PHP

use Naruko\Todoke\WebhookSignature;

$payload = file_get_contents('php://input');
$header  = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
if (! WebhookSignature::verify($payload, $header, getenv('WEBHOOK_SECRET'))) {
    http_response_code(400); exit;
}
$event = json_decode($payload, true);
// $event['request_timing'] = delivery.sent | delivery.delivered | delivery.failed | delivery.dead
// $event['id'] を冪等キーにして二重処理を防ぐ。2xx を返すと配信成功。

Node.js

const crypto = require("crypto");
function verify(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")));
  if (!parts.t || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSec) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

再送

  • 受信側が 2xx を返さないかタイムアウトすると、1 分 → 5 分 → 30 分 → 2 時間 → 6 時間の間隔で最大 5 回再送します。
  • 1 回の送信のタイムアウトは 5 秒。受信処理は短時間で 2xx を返し、重い処理は非同期に処理してください。
  • すべて失敗すると確定失敗になります。Webhook 画面から直近の配信ログ確認・手動再送ができます。
9

サンドボックスで試す

test キーなら、メッセージを送らずに Webhook 連携を試せます。 POST /sandbox/webhook-events がダミーの配信イベントを、 登録済みの test Webhook エンドポイントへ実際に署名付きで送ります。メッセージは送信されず、料金も発生しません。

curl -X POST https://hub.naruko.app/api/public/v1/sandbox/webhook-events \
  -H "Authorization: Bearer nrk_test_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"request_timing":"delivery.sent"}'
# {"event_id":"evt_…","request_timing":"delivery.sent","environment":"test","endpoints_notified":1}
  • 受信側には通常の Webhook が X-Webhook-Signature 付きで届き、data.sandbox=true が入ります。上の署名検証をそのまま試せます。
  • サンドボックスは test キー専用です。live キーで呼び出すと 403 になります。
10

SIPプロファイル

メソッドパス用途
GET/sip-profiles一覧・検索。?tag=タグ / ?q=label で部分一致
POST/sip-profiles登録。201 を返します
GET/sip-profiles/{id}1 件取得
PUT/sip-profiles/{id}編集
DELETE/sip-profiles/{id}削除

入力フィールドはいずれも任意です。 label・ display_name・ server・ sip_domain・ transport・ username・ password ほか。 tags と codecs は配列で渡します。

curl -X POST https://hub.naruko.app/api/public/v1/sip-profiles \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"label":"本社","tags":["営業","東京"],"server":"sip.example.jp","username":"u1","password":"p1"}'
  • ?tag=営業 でタグ絞り込み検索ができます。
  • レスポンスにパスワードは含まれません。設定済みかどうかを has_credentials で判断します。
  • 利用者への割り当ては利用者画面で行います。この API はプロファイル自体の管理に限ります。
11

発信プレフィックス

メソッドパス用途
GET/caller-id-prefixes一覧・検索。?q=prefix / name で部分一致
POST/caller-id-prefixes登録。並び順は自動で採番し、201 を返します
GET/caller-id-prefixes/{id}1 件取得
PUT/caller-id-prefixes/{id}編集
DELETE/caller-id-prefixes/{id}削除

入力フィールドは prefix と name が必須、 emoji は任意です。 prefix に使えるのは数字と *# だけです。