Fax Resource
We have made the difficult decision to disable Programmable Fax for all accounts on December 17, 2021. For new and inactive accounts, access to Programmable Fax is disabled effective immediately. We recognize the challenges this decision might cause and have provided detailed migration plans to prevent disruptions.
For Japan customers, please refer to this migration plan. For all other customers, please refer to this migration plan. Learn more.
The Fax resource is the main point of interaction between you and the Fax REST API.
Fax properties
| Resource Properties in REST API format | |
|---|---|
sid
|
The unique string that we created to identify the Fax resource. |
account_sid
|
The SID of the Account that created the Fax resource. |
from
|
The number the fax was sent from. Can be the phone number in E.164 format or the SIP |
to
|
The phone number that received the fax in E.164 format or a SIP URI. |
quality
|
The Fax Quality value that describes the fax quality. Can be: |
media_sid
|
The SID of the FaxMedia resource that is associated with the Fax. |
media_url
|
The Twilio-hosted URL that can be used to download fax media. Note this URL expires after 2 hours. A new URL can be fetched from the instance resource if necessary. |
num_pages
|
The number of pages contained in the fax document. |
duration
|
The time in seconds it took to transmit the fax. |
status
|
The status of the fax. Can be: |
direction
|
The transmission direction of the fax. Can be: |
api_version
|
The API version used to transmit the fax. For this version of the API, it will always be |
price
|
The price billed to transmit the fax, specified in |
price_unit
|
The ISO 4217 code of the currency used to price the fax. |
date_created
|
The date and time in GMT when the resource was created specified in ISO 8601 format. |
date_updated
|
The date and time in GMT when the resource was last updated specified in ISO 8601 format. |
links
|
The URLs of the fax's related resources. |
url
|
The absolute URL of the fax resource. |
Faxステータス
| 値 | 概要 |
|---|---|
| queued | Faxがキューイングされ、処理を待っています。 |
| processing | Faxがダウンロード、アップロードされた、または別のフォーマットに変換されました。 |
| sending | Faxが送信処理中です。 |
| delivered | Faxが正常に転送されました。 |
| receiving | Faxが受信処理中です。 |
| received | Faxが正常に受信されました。 |
| no-answer | 宛先側が応答しなかったため、Faxの送信に失敗しました。 |
| busy | 宛先側から「Busy」信号を受け取ったため、送信に失敗しました。 |
| failed | Faxの送信・受信に失敗しました。 |
| canceled | TwiMLで拒否(Reject)した、またはRest APIによるキャンセルが発生しました。 |
Fax品質
| 値 | Case-sensitive | 概要 |
|---|---|---|
| standard | true | 低品質(204x98) の解像度は、全てのFax機器に対応しています。 |
| fine | true | (Default) A medium quality (204x196) fax resolution; this quality boasts wide device support |
| superfine | true | A high quality (204x392) fax resolution; this quality may not be supported by many devices |
サブリソース
1つのサブリソース（Fax Mediaリソース）を含むFaxインスタンスです。
Create a Fax resource
https://fax.twilio.com/v1/Faxes
新しいFaxインスタンスリソースを作り、Faxを送信する。
通常の電話番号に加えて、FaxはSIP URIにも送信可能です。 詳細については、SIPの宛先にFaxを送信するを参照してください。
戻り値
単一の新規Faxインスタンスリソース、および queued ステータスと新しく作られた FaxSid を伴い、コード 201 が返ります。
Returns 403 if the From number is not valid for use as a From number, or if the To number is blocked or not reachable in accordance with the account's international permissions.
FromまたはToパラメーターが有効なE.164形式の電話番号ではない場合、Qualityの値が有効でない場合、あるいはMediaUrlまたはStatusCallbackパラメーターが有効なURLではない場合には422が返されます。
StatusCallback
If a StatusCallback URL is provided, Twilio will make an asynchronous HTTP request with one of the following statuses:
Delivered : The fax was successfully delivered
or
Failed: The fax failed. The ErrorCode and ErrorMessage parameters will be included in the callback when FaxStatus=failed.
Twilio also includes of the following form parameters in the request:
| パラメーター | 概要 |
|---|---|
| FaxSid | Faxに対する34文字の一意な識別子です |
| AccountSid | Faxの送信されたアカウント |
| From | 発信者番号、またはSIP From表示名 |
| To | 宛先の電話番号またはSIP URI |
| RemoteStationId | 受信側のFax機器からレポートされる着信先契約者識別番号 (CSID = Called Subscriber Identification) です |
| FaxStatus | 現在のFax送信のステータスです |
| ApiVersion | Fax送信に使用されたAPIバージョンで、このAPIに対しては "v1" が返されます。 |
| OriginalMediaUrl | Fax送信時に渡されたオリジナルのURLです |
| NumPages | 送信されたページ数です（成功した場合のみ） |
| MediaUrl | 送信されたオリジナルのメディアの取得に使用できるTwilioのサーバー上のメディアURLです。 URLは2時間で失効することに注意してください。 新しいURLはFaxインスタンスリソースから取得できます |
| ErrorCode | 存在する場合、問題についての詳細情報を提供するTwilioエラーコードです |
| ErrorMessage | 存在する場合、問題についての詳細メッセージです |
パラメーター
| Parameters in REST API format | |
|---|---|
to
必須
|
The phone number to receive the fax in E.164 format or the recipient's SIP URI. |
media_url
必須
|
The URL of the PDF that contains the fax. See our security page for information on how to ensure the request for your media comes from Twilio. |
quality
オプション
|
The Fax Quality value that describes the fax quality. Can be: |
status_callback
オプション
|
The URL we should call using the |
from
オプション
|
The number the fax was sent from. Can be the phone number in E.164 format or the SIP |
sip_auth_username
オプション
|
The username to use with the |
sip_auth_password
オプション
|
The password to use with |
store_media
オプション
|
Whether to store a copy of the sent media on our servers for later retrieval. Can be: |
ttl
オプション
|
How long in minutes from when the fax is initiated that we should try to send the fax. |
例 1
Fetch a Fax resource
https://fax.twilio.com/v1/Faxes/{Sid}
Fetch a Fax resource
パラメーター
| Parameters in REST API format | |
|---|---|
sid
Path
|
The Twilio-provided string that uniquely identifies the Fax resource to fetch. |
例 1
Read multiple Fax resources
https://fax.twilio.com/v1/Faxes
Lists Faxes in the account
戻り値
faxes をキーにしたリストリソース、および標準のページング情報 を伴い、コード 200が返ります。(フィルタにマッチしたFaxが存在しない場合はこのリストは空になります)
FromまたはToパラメーターが有効なE.164形式の電話番号ではない場合、422を返します。
パラメーター
| Parameters in REST API format | |
|---|---|
from
オプション
|
Retrieve only those faxes sent from this phone number, specified in E.164 format. |
to
オプション
|
Retrieve only those faxes sent to this phone number, specified in E.164 format. |
date_created_on_or_before
オプション
|
Retrieve only those faxes with a |
date_created_after
オプション
|
Retrieve only those faxes with a |
例 1
Update a Fax resource
https://fax.twilio.com/v1/Faxes/{Sid}
単一のFaxインスタンスをアップデートする
戻り値
単一のFaxインスタンスリソースが成功した場合、コード 200を返します。
Status が有効ではないかサポートしていない場合、コード 400を返します。
FaxSid が見つからない場合、コード 404 を返します。
既にこのFaxが完了しているか失敗しているため、このFaxをアップデートできなかった場合には、コード 409 を返します。注意: 現在のところ、Faxが送信をし始めたあとだと、キャンセルはできません。
パラメーター
| Parameters in REST API format | |
|---|---|
sid
Path
|
The Twilio-provided string that uniquely identifies the Fax resource to update. |
status
オプション
|
The new status of the resource. Can be only |
例 1
Delete a Fax resource
https://fax.twilio.com/v1/Faxes/{Sid}
Faxインスタンスと、関連づけられたFax Mediaインスタンスを削除します。 このアクションは取り消しできないため、ご使用には十分ご注意ください。
戻り値
このリソースとそのサブリソースの削除に成功した場合、すでに以前に削除していた場合、元から存在しなかった場合は204を返します。
Faxインスタンスがまだcompleted状態に移行していない場合、あるいはまだ削除されていない場合は409を返します。
パラメーター
| Parameters in REST API format | |
|---|---|
sid
Path
|
The Twilio-provided string that uniquely identifies the Fax resource to delete. |
例 1
ヘルプが必要ですか？
誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。