連絡

Communication。メールの通知の記録の閲覧と、連絡先（ContactEndpoint）の登録・停止・解除を提供する

説明は公開 API の契約（OpenAPI）から生成しています。

エンドポイント

GET	/v1/communication/messages
GET	/v1/communication/inbound
POST	/v1/communication/inbound
GET	/v1/communication/contacts
POST	/v1/communication/contacts
GET	/v1/communication/contacts/{id}
DELETE	/v1/communication/contacts/{id}
GET	/v1/communication/contacts/{id}/disposal
POST	/v1/communication/contacts/{id}/hold
DELETE	/v1/communication/contacts/{id}/hold
POST	/v1/communication/contacts/{id}/verify
GET	/v1/communication/contacts/{id}/verification-challenges
POST	/v1/communication/contacts/{id}/verification-challenges
POST	/v1/communication/contacts/{id}/verification-challenges/{challenge_id}/confirm
POST	/v1/communication/contacts/{id}/unverify
GET	/v1/communication/contacts/{id}/unverifications
POST	/v1/communication/contacts/{id}/reveal
POST	/v1/communication/contacts/{id}/stop
POST	/v1/communication/contacts/{id}/resume
GET	/v1/communication/contacts/{id}/resumes
GET	/v1/communication/contacts/{id}/resumes/{resume_id}
GET	/v1/communication/senders
POST	/v1/communication/senders/{name}/approve
POST	/v1/communication/senders/{name}/revoke
GET	/v1/communication/senders/{name}/revocations
GET	/v1/communication/senders/{name}/revocations/{id}

listMessages

GET/v1/communication/messages

パラメーター

名前	場所	型	必須	説明
case_id	query	string

応答

• 200 — object: 送信の記録
• default — Problem: RFC 9457 Problem Details

listInboundMessages

GET/v1/communication/inbound

communication:read が必要。外へ送ったメールへの返信。本文は社外から来た信頼できない入力

パラメーター

名前	場所	型	必須	説明
case_id	query	string

応答

• 200 — object: 受け取ったメール
• default — Problem: RFC 9457 Problem Details

receiveInboundMessage

POST/v1/communication/inbound

メールの受信の係（手元はメールの emulator）だけが呼ぶ。x-hane-inbound-secret を確かめ、in_reply_to の Message-ID の署名から組織・環境・プロジェクトと外への操作を決める。添付を 1 件ずつ文書にしてから communication.email.received を積む。元のメールがレコードを対象にしていれば、添付の値はそのレコードの候補になる。 同じ provider_message_id は 1 通にする

パラメーター

名前	場所	型	必須	説明
x-hane-inbound-secret	header	string	はい
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

リクエストの本文

application/json

名前	型	必須	説明
provider_message_id	string	はい
action_request_id	string	はい
in_reply_to	string	はい
from	string	はい
subject	string	はい
body	string	はい
attachments	object[]

応答

• 201 — InboundMessage: 受け取ったメール
• default — Problem: RFC 9457 Problem Details

listContacts

GET/v1/communication/contacts

communication:read が必要。番号は末尾 4 桁だけを残した masked で返す

応答

• 200 — object: 連絡先
• default — Problem: RFC 9457 Problem Details

createContact

POST/v1/communication/contacts

communication:contacts.write が必要。phone か email のどちらか 1 つを渡す。値は連絡先ごとの鍵で暗号化して持ち、返さない。 値が停止の台帳にあれば、止めたまま登録する

パラメーター

名前	場所	型	必須	説明
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

リクエストの本文

application/json

名前	型	必須	説明
label	string	はい	誰の連絡先か。番号やアドレスは書かない
phone	string		E.164 の電話番号（空白とハイフンは除く）
email	string		メールアドレス。小文字にそろえて持つ
purposes	string[]	はい	使ってよい連絡の目的（ContactPolicy の名前）
ai_call	boolean		AI 電話をかけてよいか。電話番号の連絡先だけ
source	manual | sync
valid_until	string | null		この日（YYYY-MM-DD）を過ぎたら使わない

応答

• 201 — ContactEndpoint: 登録した連絡先
• default — Problem: RFC 9457 Problem Details

getContact

GET/v1/communication/contacts/{id}

communication:read が必要

パラメーター

名前	場所	型	必須	説明
id	path	string	はい

応答

• 200 — ContactEndpoint: 連絡先
• default — Problem: RFC 9457 Problem Details

removeContact

DELETE/v1/communication/contacts/{id}

communication:contacts.write が必要。値の暗号文と、値が写った記録（文字起こし・返信・案件・Agent の実行と会話）を消し、 マスクした値と記録だけを残す。停止の台帳は残す。hold があれば何も消さず、state を deletion_held にして使えなくし、 disposal の status に retained_under_hold を返す。写しを読んだ実行が動いていれば、state を deletion_pending にして終わるのを待ち、 status に purging を返す。取り込んだ連絡先は消せない（409）

パラメーター

名前	場所	型	必須	説明
id	path	string	はい

応答

• 200 — object: 消した連絡先と、削除の追跡
• default — Problem: RFC 9457 Problem Details

getContactDisposal

GET/v1/communication/contacts/{id}/disposal

communication:read と、communication:contacts.write か communication:contacts.hold が必要。値の削除の追跡を返す。 連絡先の記録を消した後も読める。削除していなければ 404

パラメーター

名前	場所	型	必須	説明
id	path	string	はい

応答

• 200 — ContactDisposal: 削除の追跡
• default — Problem: RFC 9457 Problem Details

setContactHold

POST/v1/communication/contacts/{id}/hold

communication:contacts.hold が必要。hold をかけている間は、人の削除も保持の日数も取り込みの退職も値と写しを消さない。 すでに hold があれば変えずに返す。理由はイベントに載せず、communication:contacts.reveal を持つ人にだけ返す

パラメーター

名前	場所	型	必須	説明
id	path	string	はい

リクエストの本文

application/json

名前	型	必須	説明
reason	string	はい

応答

• 200 — ContactEndpoint: hold をかけた連絡先
• default — Problem: RFC 9457 Problem Details

releaseContactHold

DELETE/v1/communication/contacts/{id}/hold

communication:contacts.hold が必要。削除を受け付けていた連絡先（deletion_held）は、ここで値と写しを消す。 hold がなければ変えずに返す

パラメーター

名前	場所	型	必須	説明
id	path	string	はい

応答

• 200 — ContactEndpoint: hold を外した連絡先
• default — Problem: RFC 9457 Problem Details

verifyContact

POST/v1/communication/contacts/{id}/verify

communication:contacts.verify が必要。人が相手に確かめた連絡先を検証済みにし、communication.contact.verified を監査に残す。 未検証の連絡先には提案も実行もできない。接続から取り込んだ連絡先は値の正本から来たので要らない。2 度目は何も変えない。 Idempotency-Key は要らない。応答に停止の理由が入りうるので保存せず、要求のたびに権限を確かめる

パラメーター

名前	場所	型	必須	説明
id	path	string	はい

応答

• 200 — ContactEndpoint: 検証した連絡先
• default — Problem: RFC 9457 Problem Details

listContactChallenges

GET/v1/communication/contacts/{id}/verification-challenges

communication:contacts.verify が必要。連絡先へ送った確認の文の記録。新しい順。確認コードは返さない

パラメーター

名前	場所	型	必須	説明
id	path	string	はい
limit	query	integer

応答

• 200 — object: 確認の文の記録
• default — Problem: RFC 9457 Problem Details

sendContactChallenge

POST/v1/communication/contacts/{id}/verification-challenges

communication:contacts.verify が必要。未検証の連絡先へ、確認コードの入った決まった文を送る。相手から聞いたコードを confirm に渡すと検証済みになる。 前の確認コードは使えなくなる。止まっている・有効期限を過ぎた・検証済みの連絡先には送らない（409）。 未検証の宛先へ送るので、同じ連絡先へは 1 分の間隔を空け、24 時間で連絡先ごとに 5 通、プロジェクトで 100 通まで（429）

パラメーター

名前	場所	型	必須	説明
id	path	string	はい
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

応答

• 202 — ContactChallenge: 送る依頼を受け付けた確認の文
• default — Problem: RFC 9457 Problem Details

confirmContactChallenge

POST/v1/communication/contacts/{id}/verification-challenges/{challenge_id}/confirm

communication:contacts.verify が必要。相手から聞いた確認コードを確かめ、連絡先を検証済みにして communication.contact.verified を監査に残す。 間違いは 1 通につき 5 回まで数え（400）、使い切ると確認の文は使えなくなる（409）。24 時間で期限が切れる（409）。 Idempotency-Key は要らない。応答を保存せず、呼ぶたびに権限と回数を確かめる

パラメーター

名前	場所	型	必須	説明
id	path	string	はい
challenge_id	path	string	はい

リクエストの本文

application/json

名前	型	必須	説明
code	string	はい

応答

• 200 — ContactEndpoint: 検証した連絡先
• default — Problem: RFC 9457 Problem Details

unverifyContact

POST/v1/communication/contacts/{id}/unverify

communication:contacts.verify が必要。人か確認コードで記録した検証を取り消す。承認済みの電話・SMS・メールも実行の claim か送る直前で失敗にする。 理由は取り消しの記録に残し、communication.contact.unverified には記録の ID だけを載せる。取り込んだ連絡先は取り消せない（409）。 Idempotency-Key は要らない。応答に停止の理由が入りうるので保存しない

パラメーター

名前	場所	型	必須	説明
id	path	string	はい

リクエストの本文

application/json

名前	型	必須	説明
reason	string	はい

応答

• 200 — object: 検証を外した連絡先
• default — Problem: RFC 9457 Problem Details

listContactUnverifications

GET/v1/communication/contacts/{id}/unverifications

communication:contacts.verify が必要。検証の取り消しの記録。新しい順。理由に個人の情報が入りうるので、検証できる人だけが読む

パラメーター

名前	場所	型	必須	説明
id	path	string	はい
limit	query	integer

応答

• 200 — object: 取り消しの記録
• default — Problem: RFC 9457 Problem Details

revealContact

POST/v1/communication/contacts/{id}/reveal

communication:contacts.reveal が必要。番号（phone）かアドレス（email）の全体を返し、communication.contact.revealed を監査に残す。 Idempotency-Key は要らない。応答を保存せず、同じキーでも再送せずに、要求のたびに権限を確かめて監査に残す

パラメーター

名前	場所	型	必須	説明
id	path	string	はい

応答

• 200 — object: 番号
• default — Problem: RFC 9457 Problem Details

stopContact

POST/v1/communication/contacts/{id}/stop

communication:contacts.write が必要。相手から断られたことを記録する。番号かアドレスの停止の台帳にも入れ、 承認済みの電話・SMS・メールも実行の claim か送る直前で失敗にする

パラメーター

名前	場所	型	必須	説明
id	path	string	はい

リクエストの本文

application/json

名前	型	必須	説明
reason	string	はい

応答

• 200 — ContactEndpoint: 止めた連絡先
• default — Problem: RFC 9457 Problem Details

resumeContact

POST/v1/communication/contacts/{id}/resume

communication:contacts.resume が必要。相手から改めて同意を得たときだけ停止を解く。番号かアドレスの停止の台帳からも消す。 理由は解除の記録に残し、communication.contact.resumed には記録の ID（resume_id）だけを載せる

パラメーター

名前	場所	型	必須	説明
id	path	string	はい
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

リクエストの本文

application/json

名前	型	必須	説明
reason	string	はい

応答

• 200 — object: 停止を解いた連絡先と、解除の記録の ID
• default — Problem: RFC 9457 Problem Details

listContactResumes

GET/v1/communication/contacts/{id}/resumes

communication:contacts.resume（管理者）が必要。連絡先の解除の記録を新しい順に返す。理由を含む

パラメーター

名前	場所	型	必須	説明
id	path	string	はい
limit	query	integer

応答

• 200 — object: 解除の記録
• default — Problem: RFC 9457 Problem Details

getContactResume

GET/v1/communication/contacts/{id}/resumes/{resume_id}

communication:contacts.resume（管理者）が必要。監査のイベントの resume_id から、解除の理由を読む

パラメーター

名前	場所	型	必須	説明
id	path	string	はい
resume_id	path	string	はい

応答

• 200 — ContactResume: 解除の記録
• default — Problem: RFC 9457 Problem Details

listSenders

GET/v1/communication/senders

communication:read が必要。SenderIdentity の定義と、ドメインと発信番号の検証、承認の状態

応答

• 200 — object: 送信の名義
• default — Problem: RFC 9457 Problem Details

approveSender

POST/v1/communication/senders/{name}/approve

communication:senders.approve（管理者）が必要。一覧で見た内容の digest を渡し、いまの定義と違えば 409 で拒否する。 承認すると communication.sender.approved を監査に残す。内容を変えると承認し直すまで使えない

パラメーター

名前	場所	型	必須	説明
name	path	string	はい
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

リクエストの本文

application/json

名前	型	必須	説明
digest	string	はい	承認する人が見た内容の digest

応答

• 200 — Sender: 承認した名義
• default — Problem: RFC 9457 Problem Details

revokeSender

POST/v1/communication/senders/{name}/revoke

communication:senders.approve（管理者）が必要。承認を取り消し、communication.sender.revoked を監査に残す。 承認の済んだ未実行のメールも送らない。理由は取り消しの記録に残し、イベントには revocation_id だけを載せる

パラメーター

名前	場所	型	必須	説明
name	path	string	はい
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

リクエストの本文

application/json

名前	型	必須	説明
reason	string	はい

応答

• 200 — object: 承認を取り消した名義と、取り消しの記録の ID
• default — Problem: RFC 9457 Problem Details

listSenderRevocations

GET/v1/communication/senders/{name}/revocations

communication:senders.approve（管理者）が必要。名義の取り消しの記録を新しい順に返す。定義から消した名義の記録も読める

パラメーター

名前	場所	型	必須	説明
name	path	string	はい
limit	query	integer

応答

• 200 — object: 取り消しの記録
• default — Problem: RFC 9457 Problem Details

getSenderRevocation

GET/v1/communication/senders/{name}/revocations/{id}

communication:senders.approve（管理者）が必要。監査のイベントの revocation_id から、取り消しの理由を読む

パラメーター

名前	場所	型	必須	説明
name	path	string	はい
id	path	string	はい

応答

• 200 — SenderRevocation: 取り消しの記録
• default — Problem: RFC 9457 Problem Details