You can trigger a Speed To Lead call from your own system by sending an HTTP request to Brightcall. For example, your website or integration can send a request when a lead submits a form. You can also include lead details, specify agents, or schedule a call.

1. Prepare your widget credentials

Open the widget you want to use in the Brightcall Dashboard.

Copy the Widget Key from the Main tab.
Copy the API KEY from the same widget's Integrations tab. If the field is empty, click Generate API KEY and save the widget before using the generated key.

For more information, see How to get a Widget Key? and How to get an API Key?.

The examples below use the widget's API key. To use an account API key starting with bc_live_, follow Making a call through an API request with an account API key. The account key must have Write permission for Speed To Lead calls and leads. Legacy account API keys are not supported by this endpoint.

All code blocks below are templates. Replace every placeholder with your actual value before sending a request. Enter all phone numbers in international format, including the country code. Use your integration tool's JSON encoder for text values containing quotation marks, backslashes, or line breaks.

2. Send a POST request

Send the request to https://app.brightcall.ai/rest/v1/ext/add_call_api/.

Set the Content-Type header to application/json. Send the following JSON object directly as the request body. Do not wrap it in headers or body fields.

{
  "widget_key": "%WIDGET_KEY%",
  "api_key": "%WIDGET_API_KEY%",
  "lc_number": "%LEAD_PHONE%"
}

Field descriptions

Field	Description
`widget_key`	The key of the widget you want to trigger.
`api_key`	The API key from the same widget's Integrations tab.
`lc_number`	The lead's phone number in international format, including the country code.

3. Include optional lead details

You can include optional fields in the same JSON request body:

{
  "widget_key": "%WIDGET_KEY%",
  "api_key": "%WIDGET_API_KEY%",
  "lc_number": "%LEAD_PHONE%",
  "lc_param_name": "%LEAD_NAME%",
  "lc_param_email": "%LEAD_EMAIL%",
  "lc_param_message": "%MESSAGE%",
  "lc_number_2": "%SECOND_LEAD_PHONE%",
  "country": "%COUNTRY_CODE%"
}

Field descriptions

Field	Description
`widget_key`	The key of the widget you want to trigger.
`api_key`	The API key from the same widget's Integrations tab.
`lc_number`	The lead's phone number in international format, including the country code.
`lc_param_name`	Optional. The lead's name.
`lc_param_email`	Optional. The lead's email address.
`lc_param_message`	Optional. A message or additional information about the lead.
`lc_number_2`	Optional. The lead's second phone number in international format, including the country code.
`country`	Optional. A two-letter ISO country code used to interpret locally formatted phone numbers. Not required when phone numbers are provided in international format.

Remove any optional fields you do not need. Custom parameters can be used in notification templates to provide agents with information about the lead. For more information, see Adding custom fields and parameters.

4. Specify agents for the call (optional)

You can provide agent names and phone numbers in the request to specify agents for this call:

{
  "widget_key": "%WIDGET_KEY%",
  "api_key": "%WIDGET_API_KEY%",
  "lc_number": "%LEAD_PHONE%",
  "lc_param_name": "%LEAD_NAME%",
  "lc_param_agent01name": "%AGENT_1_NAME%",
  "lc_param_agent01phone": "%AGENT_1_PHONE%",
  "lc_param_agent02name": "%AGENT_2_NAME%",
  "lc_param_agent02phone": "%AGENT_2_PHONE%",
  "lc_param_agent03name": "%AGENT_3_NAME%",
  "lc_param_agent03phone": "%AGENT_3_PHONE%"
}

Field descriptions

Field	Description
`widget_key`	The key of the widget you want to trigger.
`api_key`	The API key from the same widget's Integrations tab.
`lc_number`	The lead's phone number in international format, including the country code.
`lc_param_name`	Optional. The lead's name.
`lc_param_agent01name`	The first agent's name.
`lc_param_agent01phone`	The first agent's phone number in international format, including the country code.
`lc_param_agent02name`	The second agent's name.
`lc_param_agent02phone`	The second agent's phone number in international format, including the country code.
`lc_param_agent03name`	The third agent's name.
`lc_param_agent03phone`	The third agent's phone number in international format, including the country code.

Provide both a name and a phone number for each agent. Use the same numeric identifier in both field names, such as 01 for the first agent, 02 for the second, and 03 for the third. Entries missing either field are ignored. Remove both fields for any agent you do not need.

Call distribution is controlled by the widget's Call routing settings. Review those settings when configuring how the supplied agents should receive calls.

If your account restricts API calls to agents registered in the account, supplied agents whose phone numbers are not registered in the account are excluded.

5. Schedule a call (optional)

To schedule a call, add future_unixstamp directly to the JSON request body. No custom field creation is required.

Replace %FUTURE_UNIXSTAMP% with an integer Unix timestamp in seconds representing the desired UTC date and time. Send this value as a JSON number, without quotation marks. This template becomes valid JSON after you replace the timestamp placeholder with a number.

{
  "widget_key": "%WIDGET_KEY%",
  "api_key": "%WIDGET_API_KEY%",
  "lc_number": "%LEAD_PHONE%",
  "future_unixstamp": %FUTURE_UNIXSTAMP%
}

Field descriptions

Field	Description
`widget_key`	The key of the widget you want to trigger.
`api_key`	The API key from the same widget's Integrations tab.
`lc_number`	The lead's phone number in international format, including the country code.
`future_unixstamp`	Optional. The desired call time as an integer Unix timestamp in seconds. Send it as a JSON number, without quotation marks.

A timestamp in the past is treated as the current time. The widget's calling rules may adjust the scheduled time. If future_unixstamp is omitted, the widget's normal calling rules apply.

You can also include the optional lead and agent fields shown in the previous examples.

6. cURL examples

POST request

curl --request POST \
  'https://app.brightcall.ai/rest/v1/ext/add_call_api/' \
  --header 'Content-Type: application/json' \
  --data '{
  "widget_key": "%WIDGET_KEY%",
  "api_key": "%WIDGET_API_KEY%",
  "lc_number": "%LEAD_PHONE%"
}'

GET request

curl --get \
  'https://app.brightcall.ai/rest/v1/ext/add_call_api/' \
  --data-urlencode 'widget_key=%WIDGET_KEY%' \
  --data-urlencode 'api_key=%WIDGET_API_KEY%' \
  --data-urlencode 'lc_number=%LEAD_PHONE%'

The GET request sends the parameters in the query string. The cURL example above URL-encodes each value automatically. You can also construct the URL directly using this template:

https://app.brightcall.ai/rest/v1/ext/add_call_api/?widget_key=%WIDGET_KEY%&api_key=%WIDGET_API_KEY%&lc_number=%LEAD_PHONE%

When constructing the URL directly, URL-encode each substituted query parameter value. These GET examples use the widget's API key. For an account API key starting with bc_live_, follow the account API key guide linked above; account API keys are not accepted in the URL.

Need help?

If you have any questions, please email [email protected].