Endpoints
Last updated
Was this helpful?
Last updated
Was this helpful?
Businesses need to to their WhatsApp Business API accounts to use it in Facebook resources such as a button on the page or After the account is connected, it can also be managed from Ads Manager.
Each client should attach the Facebook account to the WABA before the partner can work with data from META. See Meta's Official Documentation about Ads Campaign Structure.
Activate CTWA-tracking for stack (number) before configure conversions. See How to manage the tracking of Signals API.
To effectively use this API, it is essential to configure the appropriate keywords that will be tracked.
See Trackable Events (Keywords).
Here are some Best Practices that you can follow to configure keywords for the Signals API:
Define your campaign objectives: Before you begin configuring keywords, it is essential to have a clear understanding of your campaign objectives. This will help you determine the types of keywords that you should track.
Identify relevant keywords: Once you have defined your campaign objectives, you can start identifying relevant keywords. These are the words and phrases that users are likely to search for when looking for products or services related to your campaign. Try to configure "unique" keywords to track - it will help avoid false-positive results
Configure the Signals API: After identifying keywords, you can configure the Signals API to track the performance of each group of keywords.
Monitor performance: Once you have configured the Signals API to track your keywords, it is important to monitor performance regularly. This will help you identify areas where you need to make changes to optimize your campaigns.
The Signals API provides the capability to read data at various levels, offering flexibility and granularity in the data you can access. Depending on your use case, you can choose to read data at the campaign, ad group, ad, or keyword level.
Ad Overview: This provides an overview of your ad campaign's performance, including metrics such as impressions, clicks, and spend. This information is updated on a daily basis, allowing you to stay up-to-date with your campaign's progress.
Ad Daily Insights: Detailed day-by-day information is available to help you compare campaign results over time. This allows you to identify trends and patterns in your campaign's performance and make informed decisions about how to optimize your advertising efforts. This information is updated on a daily basis.
Conversion Insights: The API provides summary statistics per conversion, allowing you to track how well your keywords are performing. This information is updated on a daily basis, giving you insights into your campaign's conversion rates.
Events List: For granular information about each conversion event, the API provides an events list that is updated instantly. This feature allows you to track individual events and analyze their impact on your campaign's overall performance.
To retrieve the client_id
of clients - check Get List of Clients.
Important! Make sure you use HUB Base URL prefix for Get List of Clients.
Signals API don't support /partners endpoint.
GET
https://api.signals.360dialog.io/v1/clients/{client_id}/apps/{app_id}/facebook-accounts/
Send a GET
request and pick one Facebook account. In case of empty list - ask client to attach Facebook account first.
GET
https://api.signals.360dialog.io/v1/clients/{client_id}/apps/{app_id}/facebook-accounts/{facebook_account_id}
Send a GET
request and pick the Ad account.
For assistance with Signals endpoints, please contact our Support Team.
GET
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/ads/account/{ad_account_id}
Return paginated ad list for given app_id
and fb ad_account_id
Request Example
curl --request GET
--url [base-url] /v1/clients/client_id/apps/app_id/ads/account/ad_account_id
--header 'Accept: application/json'
--header 'Authorization: Bearer'
ad_account_id*
string
app_id*
string
client_id*
string
campaign_id
string
Example: campaign#1
limit
integer
>= 1 <= 100
Default: 20
Example: 20
offset
integer
>= 0
Default: 0
Example: 0
GET
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/ads/{ad_id}
Return ad by id
and app_id
Request Example
curl --request GET
--url [base-url]/v1/clients/client_id/apps/app_id/ads/ad_id
--header 'Accept: application/json'
--header 'Authorization: Bearer'
ad_id*
string
app_id*
string
client_id*
string
GET
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/ads/{ad_id}/insights
Return Multiple Ad Insights from Meta for given app_id
, ad_id
and date intervals
Request Example
curl --request GET
--url [base-url]/v1/clients/client_id/apps/app_id/ads/ad_id/insights
--header 'Accept: application/json'
--header 'Authorization: Bearer'
ad_id*
string
app_id*
string
client_id*
string
POST
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/ads/account/{ad_account_id}/refresh
Refresh Ad Insights for given ad account
Request Example
curl --request POST
--url [base-url]/v1/clients/{client_id}/apps/{app_id}/ads/account/{ad_account_id}/refresh
--header 'Accept: application/json'
--header 'Authorization: Bearer'
ad_account_id*
string
app_id*
string
client_id*
string
POST
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/ads/{ad_id}/refresh
Refresh Ad insights for given ad
Request Example
curl --request POST
--url [base-url]/v1/clients/client_id/apps/app_id/ads/ad_id/refresh
--header 'Accept: application/json'
--header 'Authorization: Bearer'
ad_id*
string
app_id*
string
client_id*
string
GET
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/campaigns/account/{ad_account_id}
Return paginated Campaign list for given app_id
and ad_account_id
Request Example
curl --request POST
--url [base-url]/v1/clients/client_id/apps/app_id/campaigns/account/ad_account_id
--header 'Accept: application/json'
--header 'Authorization: Bearer'
ad_account_id*
string
app_id*
string
client_id*
string
GET
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/campaigns/{campaign_id}
Return campaign by id
and app_id
Request Example
curl --request GET
--url [base-url]/v1/clients/client_id/apps/app_id/campaigns/campaign_id
--header 'Accept: application/json'
--header 'Authorization: Bearer'
campaign_id*
string
app_id*
string
client_id*
string
GET
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/campaigns/{campaign_id}/insights
Return campaign insights for given app_id
, ad_id
and date intervals
Request Example
curl --request GET
--url [base-url]/v1/clients/client_id/apps/app_id/campaigns/campaign_id/insights
--header 'Accept: application/json'
--header 'Authorization: Bearer'
ad_account_id*
string
app_id*
string
client_id*
string
POST
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/campaigns/account/{ad_account_id}/refresh
Refresh campaign insights for given Ad Account
Request Example
curl --request POST
--url [base-url]/v1/clients/client_id/apps/app_id/campaigns/account/ad_account_id/refresh
--header 'Accept: application/json'
--header 'Authorization: Bearer'
ad_account_id*
string
app_id*
string
client_id*
string
POST
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/campaigns/{campaign_id}/refresh
Refresh campaign insights for given Campaign
Request Example
curl --request POST
--url [base-url]/v1/clients/{client_id}/apps/{app_id}/campaigns/{campaign_id}/refresh
--header 'Accept: application/json'
--header 'Authorization: Bearer'
campaign_id*
string
app_id*
string
client_id*
string
Events are single instances within your conversion funnel.
Once enabled, Signals automatically tracks default events: button
, button_reply
, list_reply,
conversation
, engagement
, so there is no need for pre-configuration.
You also have the flexibility to create text-based conversions at any time by using the Event type "conversation
" and specifying the Keyword. To set up the Conversion event, you can use the endpoint described below.
button
Auto-trackable event - quick button reply from lead to business
button_reply
Auto-trackable event - quick button reply from lead to business
list
Auto-trackable event - quick list-option reply from lead to business
list_reply
Auto-trackable event - quick list-option reply from lead to business
conversation
Auto-trackable event - one lead sent 1st message to business
converted
Configurable event - pick main conversion for campaign from list of available events
engagement
Auto-trackable event - one lead sent 2nd message to business
keyword
Configurable Text-based event - "I'm ready to order!
"
Currently, the tracking of a "Conversation" Event is limited to incoming messages from outbound sources. We are actively working to enable tracking for messages sent by the business in the near future.
POST
[signals-base-url]/v1/clients/client_id/apps/app_id/converted_events
Request Example
curl --request POST
--url [base-url]/v1/clients/client_id/apps/app_id/converted_events
--header 'Accept: application/json'
--header 'Authorization: Bearer'
--header 'Content-Type: application/json'
--data '{ "campaign_id": "23851172049950328", "type": "button", "type_id": "63c14b9487dd821c0be8a0b6", "type_value": "product ordered"
app_id*
string
client_id*
string
campaign_id*
string
type*
string
Allowed values: button
button_reply
conversation
converted
engagement
keyword
link
list
list_reply
type_value
string
type_id
string
GET
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/event_types
Request Example
curl --request GET
--url [base-url]/v1/clients/client_id/apps/app_id/event_types
--header 'Accept: application/json'
--header 'Authorization: Bearer 122'
app_id*
string
client_id*
string
date_from*
string
date_to*
string
event_type_id
string
Example: keyword#1
event_type
string
Allowed values: button
button_reply
conversation
converted
engagement
keyword
link list list_reply Examples: keyword
ad_id
string
limit
integer
>= 1 <= 1000
GET
[signals-base-url]v1/clients/{client_id}/apps/{app_id}/events
Request Example
curl --request GET
--url [base-url]/v1/clients/client_id/apps/app_id/events
--header 'Accept: application/json'
--header 'Authorization: Bearer'
app_id*
string
client_id*
string
date_from*
string
date_to*
string
ad_id
string
Example: 23851172049950328
event_type
string
Allowed values: button
button_reply
conversation
converted
engagement
keyword
link
list
list_reply
limit
String
>= 1 <= 1000
event_type_id
string
Example: keyword#1
offset
String
>= 0
Default: 0
GET
[signals-base-url]v1/clients/{client_id}/apps/{app_id}/events/export
Export events in a CSV file
Request Example
curl --request GET
--url [base-url]/v1/clients/client_id/apps/app_id/events/export
--header 'Accept: application/json'
--header 'Authorization: Bearer 122'
app_id*
string
client_id*
string
date_from*
string
date_to*
string
ad_id
string
Example: 23851172049950328
event_type
string
Allowed values: button
button_reply
conversation
converted
engagement
keyword
link
list
list_reply
limit
String
>= 1 <= 1000
event_type_id
string
Example: keyword#1
offset
String
>= 0
Default: 0
GET
[signals-base-url]v1/clients/{client_id}/apps/{app_id}/standalone-events-stats
Return stats from standalone Events
Request Example
curl --request GET
--url [base-url]/v1/clients/client_id/apps/app_id/standalone-events-stats
--header 'Accept: application/json'
--header 'Authorization: Bearer 122'
app_id*
string
client_id*
string
If you want to get the conversion event for all numbers associated with the business account, you can use the group endpoint. It allows for bulk configuration.
GET
[signals-base-url]v1/clients/{client_id}/apps/{app_id}/event_groups
Request Example
curl --request GET
--url [base-url]/v1/clients/client_id/apps/app_id/event_groups
--header 'Accept: application/json'
--header 'Authorization: Bearer'
app_id*
string
client_id*
string
ad_id
string
limit
integer
event_type_id
string
Examples: keyword#1
event_type
string
Allowed values: button
button_reply
conversation
converted
engagement
keyword
link
list
list_reply
offset
integer
status
string
Allowed values: active
archived
GET
[signals-base-url]v1/clients/{client_id}/apps/{app_id}/facebook-accounts
Request Example
curl --request POST
--url [base-url]/v1/clients/client_id/apps/app_id/facebook-accounts
--header 'Accept: application/json'
--header 'Authorization: Bearer 122'
--header 'Content-Type: application/json'
--data '{ "temporary_token": "63c14b9487dd821c0be8a0b6" }'
app_id*
string
client_id*
string
POST
[signals-base-url]/v1/clients/client_id/apps/app_id/facebook-accounts
Request Example
curl --request POST
--url [base-url]/v1/clients/client_id/apps/app_id/facebook-accounts
--header 'Accept: application/json'
--header 'Authorization: Bearer 122'
--header 'Content-Type: application/json'
--data '{ "temporary_token": "63c14b9487dd821c0be8a0b6" }'
client_id*
string
app_id*
string
temporary_token*
string
GET
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/facebook-accounts/{facebook_account_id}
Request Example
curl --request GET
--url [base-url]/v1/clients/client_id/apps/app_id/facebook-accounts/facebook_account_id
--header 'Accept: application/json'
--header 'Authorization: Bearer 122'
client_id*
string
app_id*
string
facebook_account_id*
string
POST
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/facebook-accounts
Request Example
curl --request POST
--url [base-url]/v1/clients/client_id/apps/app_id/facebook-accounts/facebook_account_id/facebook-ad-accounts/facebook_ad_account_id/facebook-ad-campaign
--header 'Accept: application/json'
--header 'Authorization: Bearer'
--header 'Content-Type: application/json'
--data '{ "campaign_name": "TEST CTWA POC", "daily_budget": 100, "start_time": "2023-09-18T11:36:41.356737", "end_time": "2023-09-19T12:36:41.356747", "billing_event": "IMPRESSIONS", "body": "Grow your business 5x", "title": "Chat with us", "page_id": "460293477343848", "targeting": { "age_min": 18, "age_max": 65, "gender": "men", "geo_locations": { "countries": [ "US" ], "cities": [ { "key": "1910415" } ] } }, "image_hash": "a275aa36c7b2e6d0105bf683c55e7bd6" }'
app_id*
string
client_id*
string
facebook_ad_account_id*
string
facebook_account_id*
string
campaign_name*
string
Example: TEST CTWA POC
title*
string
Example: Chat with us
body*
string
Example: Grow your business 5x
billing_event*
string
Allowed values: IMPRESSIONS
LINK_CLICKS
end_time*
string <date-time>
Example: 2023-09-19T12:36:41.356747
start_time*
string <date-time>
Example: 2023-09-18T11:36:41.356737
daily_budget*
integer
Example: 100
gender*
string
Allowed values: all
men
women
age_max*
integer
<= 65
targeting*
String
Facebook ad campaign targeting configuration
page_id*
string
Example: 460293477343848
key*
string
Example: 1910415
cities
array
countries
array[string]
Example: ["US"
]
geo_locations*
Targeting geo locations
image_hash*
string
Example: a275aa36c7b2e6d0105bf683c55e7bd6
age_min*
integer
>= 18
GET
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/facebook-accounts/{facebook_account_id}/facebook-ad-accounts/{facebook_ad_account_id}/facebook-pages
Request Example
curl --request GET
--url [base-url]/v1/clients/client_id/apps/app_id/facebook-accounts/facebook_account_id/facebook-ad-accounts/facebook_ad_account_id/facebook-pages
--header 'Accept: application/json'
--header 'Authorization: Bearer'
client_id*
string
app_id*
string
facebook_account_id*
string
facebook_ad_account_id*
string
GET
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/facebook-accounts/{facebook_account_id}/facebook-ad-accounts/{facebook_ad_account_id}/facebook-ad-images
Request Example
curl --request GET
--url [base-url]/v1/clients/client_id/apps/app_id/facebook-accounts/facebook_account_id/facebook-ad-accounts/facebook_ad_account_id/facebook-ad-images
--header 'Accept: application/json'
--header 'Authorization: Bearer 122'
client_id*
string
app_id*
string
facebook_account_id*
string
POST
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/facebook-accounts/{facebook_account_id}/facebook-ad-accounts/{facebook_ad_account_id}/upload-facebook-ad-image
Request Example
curl --request POST
--url [base-url]/v1/clients/client_id/apps/app_id/facebook-accounts/facebook_account_id/facebook-ad-accounts/facebook_ad_account_id/upload-facebook-ad-image
--header 'Accept: application/json'
--header 'Authorization: Bearer 122'
--header 'Content-Type: multipart/form-data'
--form img=
app_id*
string
client_id*
string
facebook_ad_account_id*
string
facebook_account_id*
string
img*
string
GET
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/facebook-accounts/{facebook_account_id}/facebook-ad-accounts/{facebook_ad_account_id}/targeting-geolocations
Request Example
curl --request GET
--url [base-url]/v1/clients/client_id/apps/app_id/facebook-accounts/facebook_account_id/facebook-ad-accounts/facebook_ad_account_id/targeting-geolocations
--header 'Accept: application/json'
--header 'Authorization: Bearer '
client_id*
string
app_id*
string
facebook_account_id*
string
facebook_ad_account_id*
string
query*
string
GET
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/keywords
Request Example
curl --request GET
--url [base-url]/v1/clients/client_id/apps/app_id/keywords
--header 'Accept: application/json'
--header 'Authorization: Bearer 122'
client_id*
string
app_id*
string
ad_id
string
Example: 23851172049950328
offset
integer
limit
integer
is_shared
boolean
Example: true
status
string
Allowed values: active
archived
POST
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/keywords
Example Request
curl --request POST
--url [base-url]/v1/clients/client_id/apps/app_id/keywords
--header 'Accept: application/json'
--header 'Authorization: Bearer 122'
--header 'Content-Type: application/json'
--data '{ "keyword": "Product ordered" }'
client_id*
string
app_id*
string
ad_id
string
Example: 23851172049950328
keyword*
string
Example: Product ordered
GET
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/keywords/{keyword_id}
Example Request
curl --request GET
--url [base-url]/v1/clients/client_id/apps/app_id/keywords/keyword_id
--header 'Accept: application/json'
--header 'Authorization: Bearer 122'
app_id*
string
client_id*
string
keyword_id*
string
ad_id
string
is_shared
boolean
DELETE
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/keywords/{keyword_id}
Example Request
curl --request DELETE
--url [base-url]/v1/clients/client_id/apps/app_id/keywords/keyword_id
--header 'Accept: application/json'
--header 'Authorization: Bearer 122'
app_id*
string
keyword_id*
string
client_id*
string
ad_id
string
delete
boleean
PATCH
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/keywords/{keyword_id}
Disable existing keyword and create a new one
app_id*
string
keyword_id*
string
client_id*
string
ad_id
string
keyword*
string
Example: Product ordered
POST
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/keywords/shared
Create shared keyword > This keyword will be "shared" with all phone numbers associated with the account.
client_id*
string
app_id*
string
keyword*
string
Example: Product ordered
POST
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/sales
Request Example
curl --request POST
--url [signals-base-url]/v1/clients/client_id/apps/app_id/sales
--header 'Accept: application/json'
--header 'Authorization: Bearer 122'
--header 'Content-Type: application/json'
--data '{ "phone": "123456789", "amount": 100 }'
app_id*
string
client_id*
string
phone*
string
Example: 123456789
amount*
number
Example: 100
GET
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/ads/{ad_id}/sale-insights
Return sale insight for given app_id
, ad_id
and date
intervals
Request example
curl --request GET
--url[signals-base-url]/v1/clients/client_id/apps/app_id/ads/ad_id/sale-insights
--header 'Accept: application/json'
--header 'Authorization: Bearer 122'
ad_id*
string
client_id*
string
app_id*
string
date_from*
string
date_to*
string
You can subscribe for instant postback for each conversion keyword. When you opt-in for this feature, the Signals API will automatically call your API every time the system detects a conversion event, allowing you to receive real-time updates on your campaign's performance.
GET
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/ads/{ad_id}/signals
Example Request
curl --request GET
--url [base-url]/v1/clients/client_id/apps/app_id/ads/ad_id/signals
--header 'Accept: application/json'
--header 'Authorization: Bearer'
ad_id*
string
client_id*
string
app_id*
string
POST
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/ads/{ad_id}/signal
Example Request
curl --request POST
--url [base-url]/v1/clients/client_id/apps/app_id/ads/ad_id/signals
--header 'Accept: application/json'
--header 'Authorization: Bearer'
ad_id*
string
client_id*
string
app_id*
string
url
string <uri>
>= 1 characters
| <= 65536 characters
GET
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/ads/{ad_id}/signal
Get Signal url of Ad
Example Request
curl --request GET
--url [base-url]/v1/clients/client_id/apps/app_id/ads/ad_id/signal
--header 'Accept: application/json'
--header 'Authorization: Bearer '
ad_id*
string
client_id*
string
app_id*
string
POST
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/ads/{ad_id}/keywords/{keyword_id}/signal
Set signal of keyword
Example Request
curl --request POST
--url [base-url]/v1/clients/client_id/apps/app_id/ads/ad_id/keywords/keyword_id/signal
--header 'Accept: application/json'
--header 'Authorization: Bearer 122'
--header 'Content-Type: application/json'
--data '{ "url": "https://example.com" }'
keyword_id*
string
client_id*
string
app_id*
string
ad_id*
string
url
string<url>
GET
[signals-base-url]/v1/clients/{client_id}/apps/{app_id}/ads/{ad_id}/keywords/{keyword_id}/signal
Example Request
curl --request GET
--url [base-url]/v1/clients/client_id/apps/app_id/ads/ad_id/keywords/keyword_id/signal
--header 'Accept: application/json'
--header 'Authorization: Bearer'
ad_id*
string
client_id*
string
app_id*
string
keyword_id*
string
POST
[signals-base-url]/v1/clients/client_id/apps/app_id/ads/ad_id/events/session_start/signal
Example Request
curl --request POST
--url [base-url]v1/clients/client_id/apps/app_id/ads/ad_id/events/session_start/signal
--header 'Accept: application/json'
--header 'Authorization: Bearer 122'
--header 'Content-Type: application/json'
--data '{ "url": "https://example.com" }'
client_id*
String
app_id*
String
ad_id*
String
event_type*
str
Allowed value: session_start
GET
[signals-base-url]/v1/clients/client_id/apps/app_id/ads/ad_id/events/session_start/signal
Example Request
curl --request POST
--url [base-url]/v1/clients/client_id/apps/app_id/ads/ad_id/events/session_start/signal
--header 'Accept: application/json'
--header 'Authorization: Bearer 122'
--header 'Content-Type: application/json'
--data '{ "url": "https://example.com" }'
client_id*
string
app_id*
string
ad_id*
string
event_type*
string
Allowed value: session_start