API reference

Communication

Email notification records and contact endpoints.

Generated from the public API contract (OpenAPI). Descriptions in the contract are written in Japanese.

Endpoints


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

Parameters

Name	In	Type	Required	Description
`case_id`	query	string

Responses

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

listInboundMessages

GET/v1/communication/inbound

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

Parameters

Name	In	Type	Required	Description
`case_id`	query	string

Responses

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 通にする

Parameters

Name	In	Type	Required	Description
`x-hane-inbound-secret`	header	string	yes
`Idempotency-Key`	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

Request body

application/json

Name	Type	Required
`provider_message_id`	string	yes
`action_request_id`	string	yes
`in_reply_to`	string	yes
`from`	string	yes
`subject`	string	yes
`body`	string	yes
`attachments`	object[]

Responses

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

listContacts

GET/v1/communication/contacts

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

Responses

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

createContact

POST/v1/communication/contacts

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

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

Request body

application/json

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

Responses

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

getContact

GET/v1/communication/contacts/{id}

communication:read が必要

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes

Responses

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）

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes

Responses

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

getContactDisposal

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

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

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes

Responses

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

setContactHold

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

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

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes

Request body

application/json

Name	Type	Required	Description
`reason`	string	yes

Responses

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

releaseContactHold

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

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

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes

Responses

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 は要らない。応答に停止の理由が入りうるので保存せず、要求のたびに権限を確かめる

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes

Responses

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

listContactChallenges

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

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

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`limit`	query	integer

Responses

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）

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`Idempotency-Key`	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

Responses

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 は要らない。応答を保存せず、呼ぶたびに権限と回数を確かめる

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`challenge_id`	path	string	yes

Request body

application/json

Name	Type	Required	Description
`code`	string	yes

Responses

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 は要らない。応答に停止の理由が入りうるので保存しない

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes

Request body

application/json

Name	Type	Required	Description
`reason`	string	yes

Responses

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

listContactUnverifications

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

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

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`limit`	query	integer

Responses

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 は要らない。応答を保存せず、同じキーでも再送せずに、要求のたびに権限を確かめて監査に残す

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes

Responses

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

stopContact

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

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

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes

Request body

application/json

Name	Type	Required	Description
`reason`	string	yes

Responses

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

resumeContact

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

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

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`Idempotency-Key`	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

Request body

application/json

Name	Type	Required	Description
`reason`	string	yes

Responses

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

listContactResumes

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

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

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`limit`	query	integer

Responses

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

getContactResume

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

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

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`resume_id`	path	string	yes

Responses

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

listSenders

GET/v1/communication/senders

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

Responses

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

approveSender

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

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

Parameters

Name	In	Type	Required	Description
`name`	path	string	yes
`Idempotency-Key`	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

Request body

application/json

Name	Type	Required	Description
`digest`	string	yes	承認する人が見た内容の digest

Responses

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

revokeSender

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

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

Parameters

Name	In	Type	Required	Description
`name`	path	string	yes
`Idempotency-Key`	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

Request body

application/json

Name	Type	Required	Description
`reason`	string	yes

Responses

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

listSenderRevocations

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

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

Parameters

Name	In	Type	Required	Description
`name`	path	string	yes
`limit`	query	integer

Responses

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

getSenderRevocation

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

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

Parameters

Name	In	Type	Required	Description
`name`	path	string	yes
`id`	path	string	yes

Responses

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