Sending Commands
A Programmable Fax API command is sent with a fax_id
. The fax_id
allows a user to communicate to Telnyx the fax
the user wants to take an action on.
Authenticating Your Fax Request
To send a Programmable Fax API command from your application, you must authenticate your request by sending the Authorization header with a value of a key:secret
pair. A key and secret can be retrieved from Auth in the Mission Control Portal under the tab Auth v2, or via the Telnyx API.
Credential Type | HTTP Header Format |
---|---|
Key + Secret | Authorization: Basic base64("key:secret") |
Available Commands and their Expected Webhooks
Telnyx sends webhooks to update on the status of Programmable Fax. Webhooks will also be sent in response to requests to list and delete faxes.
Command | Associated Webhooks |
---|---|
Send a fax | fax.queued fax.media.processed fax.sending.started fax.delivered fax.failed |
Response when sending command
When you send a Programmable Fax API Command, you will immediately receive an http response. Responses include, but are not limited to:
HTTP Status Code | Message | Description |
---|---|---|
202 | OK | The request succeeded. |
403 | Forbidden | The request was valid, however the user is not authorized to perform this action. |
404 | Not Found | The requested resource could not be found. |
422 | Invalid Parameters | The request has invalid parameters. |
429 | Too many requests | There is a limit for outbound faxes of 2000 faxes being processed at the same time. |
Webhook examples
On successful delivery
{
"event_type": "fax.delivered",
"id": "3320554f-6b74-4138-a74b-a1e2ec7eaf8b",
"occurred_at": "2022-01-07T10:01:43.677850Z",
"payload": {
"call_duration_secs": 79,
"connection_id": "1232154810234",
"direction": "outbound",
"fax_id": "c62be5bc-9b13-4b6c-abda-34dd8b541287",
"from": "+19459457421",
"original_media_url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
"page_count": 1,
"status": "delivered",
"to": "+13129457420",
"user_id": "bdaa1f9f-1018-4156-867d-6c4ac9f556eb"
}
}
On failed delivery
{
"event_type": "fax.failed",
"id": "d906ecda-db21-428e-9ca0-74dae7e7c144",
"occurred_at": "2022-01-05T22:23:46.888808Z",
"payload": {
"connection_id": "1232154810234",
"direction": "outbound",
"failure_reason": "user_busy",
"fax_id": "f7b303ed-674c-4962-951b-848380510893",
"from": "+19459457421",
"original_media_url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
"status": "failed",
"to": "+13129457420",
"user_id": "417b0cc2-39e0-4ab9-b116-e56543649aa9"
}
}
Possible failure reasons
Inspect the failure_reason
field in webhook's payload to debug failed deliveries of your faxes. The possible failure reasons are:
account_disabled
connection_channel_limit_exceeded
destination_invalid
destination_not_in_countries_whitelist
destination_not_in_service_plan
destination_unreachable
fax_signaling_error
invalid_ecm_response_from_receiver
no_outbound_profile
outbound_profile_channel_limit_exceeded
outbound_profile_daily_spend_limit_exceeded
receiver_call_dropped
receiver_communication_error
receiver_decline
receiver_incompatible_destination
receiver_invalid_number_format
receiver_no_answer
receiver_no_response
receiver_recovery_on_timer_expire
receiver_unallocated_number
service_unavailable
user_busy
user_channel_limit_exceeded