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 TypeHTTP Header Format
Key + SecretAuthorization: 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 CodeMessageDescription
202OKThe request succeeded.
403ForbiddenThe request was valid, however the user is not authorized to perform this action.
404Not FoundThe requested resource could not be found.
422Invalid ParametersThe request has invalid parameters.
429Too many requestsThere 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?