Call Settings

Call icon visibility controls

You can hide the call icon in a Messenger thread by setting icon_enabled to false using the Messenger Call Settings API. By default, the call icon visibility is set to true for all Pages. When icon_enabled is set to false, the call icon won't display in any threads for that Page.

Additionally, users can't initiate calls from Missed Call or Completed Call messages when icon visibility is turned off. You can send a Call Prompt message to allow the user to call your business.

Use this API to enable or disable the call icon for the Page.

POST /<PAGE_ID>/messenger_call_settings
{
    "icon_enabled" : <boolean_value>
}

Example response

{
  "result": "success/failure"
}

Error response

The following errors can happen:

• Incorrect permissions for the API request

For more details on these errors, see the Messenger Platform error codes reference.

Send a call prompt message using Messenger Send API

You can send a new template call_prompt. This template contains a button that lets the consumer initiate a call with your business. The consumer can initiate the call for the number of days you specify when sending the message. Use ttl_days to specify how many days the calling button remains active for the consumer. If you don't specify ttl_days, the calling button is active for 7 days by default.

Call the Messenger Send API with the following payload to send a Call CTA to the consumer.

Example response

{
  "recipient_id": "<PSID>"
  "message_id": "<Message-id>"
}

Error response

The following errors can happen:

• The Page does not have calling enabled
• The Page does not have the correct permissions to send messages
• The Page is sending the message outside of the allowed messaging window

For more details on these errors, see the Messenger Platform error codes reference.

Call hours

Use this API to update the settings. This updates the same setting on Meta Business Suite and the Messenger app. To set the call hours for a Page, make an API request to the messenger_call_settings endpoint and set call_hours. Updates in existing chats are near real-time. When you set hours, any previous settings are erased. Any days you don't set default to closed.

POST /<PAGE_ID>/messenger_call_settings
{
    "call_hours": {
      "timezone_id": "America/Los_Angeles",
      "weekly_operating_hours": [
        {
          "day_of_week": "MONDAY",
          "open_time": "0900",
          "close_time": "1700"
        },
        {
          "day_of_week": "TUESDAY",
          "open_time": "0930",
          "close_time": "1830"
        }
      ]
    }
}

Example response

{
  "success": true
}

Error response

The following errors can happen:

• Invalid page-id
• Invalid time for weekly call hours
• Close time cannot be before open time
• Duplicate day in request

For more details on these errors, see the Messenger Platform error codes reference.

Get call hours

To retrieve the current call hours for a Page, send a GET request to the messenger_call_settings endpoint.

GET /<PAGE_ID>/messenger_call_settings?fields=call_hours

Example response

{
    "call_hours": {
      "timezone_id": "America/Los_Angeles",
      "weekly_operating_hours": [
        {
          "day_of_week": "MONDAY",
          "open_time": "0900",
          "close_time": "1700"
        },
        {
          "day_of_week": "TUESDAY",
          "open_time": "0930",
          "close_time": "1830"
        }
      ]
    }
}

Error response

The following errors can happen:

• Invalid page-id

For more details on these errors, see the Messenger Platform error codes reference.

Call settings update webhook

You can subscribe to the call_settings_update webhook to receive notifications whenever your call settings change. For example, if you disable calling via Messenger or update your call hours, this information is sent as a webhook to the subscribed applications.

{
  "object": "page",
  "entry": [
    {
      "id": <PAGE_ID>,
      "time": 1671644824,
      "call_settings": {
          "audio_enabled": true,
          "icon_enabled": true,
          "call_routing": "PARTNERS",
          "call_hours": {
              "timezone_id": "timezone_id",
              "weekly_operating_hours": [
                 {
                   "day_of_week": "MONDAY",
                   "open_time": "0400",
                   "close_time": "1020"
                 },
                 {
                    "day_of_week": "TUESDAY",
                    "open_time": "0108",
                    "close_time": "1020"
                 }
              ],
          },
      }
    }
  ]
}

Inbound call routing

You can select whether incoming calls ring Meta apps such as Business Inbox in Messenger or third-party apps integrated with the Messenger Calling API. To configure where incoming calls are routed, make an API request to the messenger_call_settings endpoint and set call_routing.

Use this API to update the settings. This setting only affects consumer-initiated calls. For business-initiated calls, the Page can always place calls using both Meta-owned platforms and third-party applications.

Call Platform: Determines where the business will receive incoming call rings.

Prerequisites: App must be subscribed to calls webhook to set ring_target to PARTNERS.

POST /<PAGE_ID>/messenger_call_settings
{
    "call_routing": {
        "ring_target": <RING_TARGET>
    }
}

Example response

{
  "success": true
}

Error response

The following errors can happen:

• Invalid page-id
• Invalid call routing value
• Page not yet eligible

For more details on these errors, see the Messenger Platform error codes reference.

Get call routing

To retrieve the current call routing for a Page, send a GET request to the messenger_call_settings endpoint.

GET /<PAGE_ID>/messenger_call_settings?fields=call_routing

Example response

{
  "call_routing": {
    "ring_target": "PARTNERS"
  }
}

Error response

The following errors can happen:

• Invalid page-id

For more details on these errors, see the Messenger Platform error codes reference.