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

Was this page helpful?