Endpoints

Businesses need to connect their Facebook page to their WhatsApp Business API accounts to use it in Facebook resources such as a button on the page or Click to WhatsApp ads. After the account is connected, it can also be managed from Ads Manager.

Ads Campaign Structure

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.

Meta's Ads Campaign Structure

Configuring Tracking Keywords

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).

Best Practices

Here are some Best Practices that you can follow to configure keywords for the Signals API:

1. 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.

2. 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

3. Configure the Signals API: After identifying keywords, you can configure the Signals API to track the performance of each group of keywords.

4. 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.

Try to configure unique keywords to track - it will help avoid false-positive results. General keywords like "Yes", "No", "Hello", "Thank you", etc. - can be a way to ruin statistics for conversion data.

Analyzing Results

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.

Signals Endpoints

Base-URL

Auth and Base URL

Retrieve Client's Facebook Accounts IDs

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.

Retrieve list of attached Facebook accounts of the client

GEThttps://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.

200: OK

Example

[​
  {​
    "id": "2311334042249923",​
    "email": "[e-mail]"​
  }​
​]

Retrieve list of Ad accounts related to the client's Facebook account

GEThttps://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.

200: OK

[​
  {​
    "id": "1011872785512566",​
    "name": "Advertiser Company Name"​
  }​
​]

For assistance with Signals endpoints, please contact our Support Team.

Meta Ads

Get Ads

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'

Path Parameters

Name	Type	Description
ad_account_id*	string
app_id*	string
client_id*	string

Query Parameters

Name	Type	Description
campaign_id	string	Example: campaign#1
limit	integer	>= 1 <= 100 Default: 20 Example: 20
offset	integer	>= 0 Default: 0 Example: 0

200: OK

{
  "data": [
    {
      "id": "23851172049950328",
      "ad_account_id": "174816537731874",
      "ad_account": {
        "name": "360dialog.com - Ad-Account",
        "currency": "EUR"
      },
      "ad_set": {
        "name": "Spot ad set",
        "status": "ACTIVE"
      },
      "name": "Spot image",
      "status": "ACTIVE",
      "created_time": "2022-11-01T10:05:08+01:00",
      "updated_time": "2022-11-30T14:05:08+01:00",
      "campaign": {
        "id": "23851172049950328",
        "ad_account_id": "174816537731874",
        "ad_account": {
          "name": "360dialog.com - Ad-Account",
          "currency": "EUR"
        },
        "name": "Spot image",
        "status": "ACTIVE",
        "start_time": "2022-11-01T10:05:08+01:00",
        "stop_time": "2022-11-30T14:05:08+01:00",
        "page": {
          "id": "460293477343848"
        },
        "insight": {
          "campaign_id": "23851172049950328",
          "date": "2023-02-28T08:01:15.667000",
          "clicks": 1234,
          "cpc": 0.3,
          "cpm": 3.4,
          "ctr": 1.4,
          "impressions": 6789,
          "spend": 123.45,
          "currency": "EUR",
          "sessions": 6789,
          "cost_per_session": 0.45,
          "cvr_clicks_to_sessions": 0.45,
          "unique_users": 5999,
          "cost_per_unique_user": 0.45,
          "cvr_clicks_to_unique_users": 0.45,
          "engaged": 5999,
          "cost_per_engagement": 0.45,
          "cvr_unique_users_to_engaged": 0.45,
          "converted": 5999,
          "cost_per_conversions": 0.45,
          "cvr_unique_users_to_converted": 0.45,
          "events": {
            "conversation": 2,
            "keyword": 0
          },
          "keywords": [
            {
              "keyword": "Product ordered",
              "events": 7,
              "cvr": 1.23
            }
          ]
        },
        "sale_insight": {
          "ad_id": "23851172049950328",
          "date": "2022-10-23T18:54:35",
          "revenue": 500,
          "count": 1,
          "roas": 3,
          "cvr": 2.04,
          "cvr_cost": 1
        }
      },
      "page": {
        "id": "460293477343848"
      },
      "insight": {
        "ad_id": "23851172049950328",
        "date": "2023-02-28T08:01:15.667000",
        "clicks": 1234,
        "cpc": 0.3,
        "cpm": 3.4,
        "ctr": 1.4,
        "impressions": 6789,
        "spend": 123.45,
        "currency": "EUR",
        "sessions": 6789,
        "cost_per_session": 0.45,
        "cvr_clicks_to_sessions": 0.45,
        "unique_users": 5999,
        "cost_per_unique_user": 0.45,
        "cvr_clicks_to_unique_users": 0.45,
        "engaged": 5999,
        "cost_per_engagement": 0.45,
        "cvr_unique_users_to_engaged": 0.45,
        "converted": 5999,
        "cost_per_conversions": 0.45,
        "cvr_unique_users_to_converted": 0.45,
        "events": {
          "conversation": 2,
          "keyword": 0
        },
        "keywords": [
          {
            "keyword": "Product ordered",
            "events": 7,
            "cvr": 1.23
          }
        ]
      },
      "sale_insight": {
        "ad_id": "23851172049950328",
        "date": "2022-10-23T18:54:35",
        "revenue": 500,
        "count": 1,
        "roas": 3,
        "cvr": 2.04,
        "cvr_cost": 1
      },
      "active_event_groups_count": 0
    }
  ],
  "total_count": 0,
  "offset": 0,
  "limit": 0
}

Get Ad

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'

Path Parameters

Name	Type	Description
ad_id*	string
app_id*	string
client_id*	string

200: OK

{
  "id": "23851172049950328",
  "ad_account_id": "174816537731874",
  "ad_account": {},
  "ad_set": {},
  "name": "Spot image",
  "status": "ACTIVE",
  "created_time": "2022-11-01T10:05:08+01:00",
  "updated_time": "2022-11-30T14:05:08+01:00",
  "campaign": {
    "id": "23851172049950328",
    "ad_account_id": "174816537731874",
    "ad_account": {
      "name": "360dialog.com - Ad-Account",
      "currency": "EUR"
    },
    "name": "Spot image",
    "status": "ACTIVE",
    "start_time": "2022-11-01T10:05:08+01:00",
    "stop_time": "2022-11-30T14:05:08+01:00",
    "page": {
      "id": "460293477343848"
    },
    "insight": {
      "campaign_id": "23851172049950328",
      "date": "2023-02-28T08:01:15.667000",
      "clicks": 1234,
      "cpc": 0.3,
      "cpm": 3.4,
      "ctr": 1.4,
      "impressions": 6789,
      "spend": 123.45,
      "currency": "EUR",
      "sessions": 6789,
      "cost_per_session": 0.45,
      "cvr_clicks_to_sessions": 0.45,
      "unique_users": 5999,
      "cost_per_unique_user": 0.45,
      "cvr_clicks_to_unique_users": 0.45,
      "engaged": 5999,
      "cost_per_engagement": 0.45,
      "cvr_unique_users_to_engaged": 0.45,
      "converted": 5999,
      "cost_per_conversions": 0.45,
      "cvr_unique_users_to_converted": 0.45,
      "events": {
        "conversation": 2,
        "keyword": 0
      },
      "keywords": [
        {
          "keyword": "Product ordered",
          "events": 7,
          "cvr": 1.23
        }
      ]
    },
    "sale_insight": {
      "ad_id": "23851172049950328",
      "date": "2022-10-23T18:54:35",
      "revenue": 500,
      "count": 1,
      "roas": 3,
      "cvr": 2.04,
      "cvr_cost": 1
    }
  },
  "page": {},
  "insight": {
    "ad_id": "23851172049950328",
    "date": "2023-02-28T08:01:15.667000",
    "clicks": 1234,
    "cpc": 0.3,
    "cpm": 3.4,
    "ctr": 1.4,
    "impressions": 6789,
    "spend": 123.45,
    "currency": "EUR",
    "sessions": 6789,
    "cost_per_session": 0.45,
    "cvr_clicks_to_sessions": 0.45,
    "unique_users": 5999,
    "cost_per_unique_user": 0.45,
    "cvr_clicks_to_unique_users": 0.45,
    "engaged": 5999,
    "cost_per_engagement": 0.45,
    "cvr_unique_users_to_engaged": 0.45,
    "converted": 5999,
    "cost_per_conversions": 0.45,
    "cvr_unique_users_to_converted": 0.45,
    "events": {
      "conversation": 2,
      "keyword": 0
    },
    "keywords": [
      {
        "keyword": "Product ordered",
        "events": 7,
        "cvr": 1.23
      }
    ]
  },
  "sale_insight": {
    "ad_id": "23851172049950328",
    "date": "2022-10-23T18:54:35",
    "revenue": 500,
    "count": 1,
    "roas": 3,
    "cvr": 2.04,
    "cvr_cost": 1
  }
}

422: Unprocessable Entity

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Get Ads Insights

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'

Path Parameters

Name	Type	Description
ad_id*	string
app_id*	string
client_id*	string

200: OK

[
  {
    "ad_id": "23851172049950328",
    "date": "2023-02-28T08:01:15.667000",
    "clicks": 1234,
    "cpc": 0.3,
    "cpm": 3.4,
    "ctr": 1.4,
    "impressions": 6789,
    "spend": 123.45,
    "currency": "EUR",
    "sessions": 6789,
    "cost_per_session": 0.45,
    "cvr_clicks_to_sessions": 0.45,
    "unique_users": 5999,
    "cost_per_unique_user": 0.45,
    "cvr_clicks_to_unique_users": 0.45,
    "engaged": 5999,
    "cost_per_engagement": 0.45,
    "cvr_unique_users_to_engaged": 0.45,
    "converted": 5999,
    "cost_per_conversions": 0.45,
    "cvr_unique_users_to_converted": 0.45,
    "events": {
      "conversation": 2,
      "keyword": 0
    },
    "keywords": [
      {
        "keyword": "Product ordered",
        "events": 7,
        "cvr": 1.23
      }
    ]
  }
]

422: Unprocessable Entity

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Refresh Ads Insights

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'

Path Parameters

Name	Type	Description
ad_account_id*	string
app_id*	string
client_id*	string

200: OK

{
  "success": true
}

Refresh Ad Insights

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'

Path Parameters

Name	Type	Description
ad_id*	string
app_id*	string
client_id*	string

200: OK

{
  "success": true
}

Meta Campaigns

Get Campaigns

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'

Path Parameters

Name	Type	Description
ad_account_id*	string
app_id*	string
client_id*	string

200: OK

{
  "data": [
    {
      "id": "23851172049950328",
      "ad_account_id": "174816537731874",
      "ad_account": {
        "name": "360dialog.com - Ad-Account",
        "currency": "EUR"
      },
      "name": "Spot image",
      "status": "ACTIVE",
      "start_time": "2022-11-01T10:05:08+01:00",
      "stop_time": "2022-11-30T14:05:08+01:00",
      "page": {
        "id": "460293477343848"
      },
      "insight": {
        "campaign_id": "23851172049950328",
        "date": "2023-02-28T08:01:15.667000",
        "clicks": 1234,
        "cpc": 0.3,
        "cpm": 3.4,
        "ctr": 1.4,
        "impressions": 6789,
        "spend": 123.45,
        "currency": "EUR",
        "sessions": 6789,
        "cost_per_session": 0.45,
        "cvr_clicks_to_sessions": 0.45,
        "unique_users": 5999,
        "cost_per_unique_user": 0.45,
        "cvr_clicks_to_unique_users": 0.45,
        "engaged": 5999,
        "cost_per_engagement": 0.45,
        "cvr_unique_users_to_engaged": 0.45,
        "converted": 5999,
        "cost_per_conversions": 0.45,
        "cvr_unique_users_to_converted": 0.45,
        "events": {
          "conversation": 2,
          "keyword": 0
        },
        "keywords": [
          {
            "keyword": "Product ordered",
            "events": 7,
            "cvr": 1.23
          }
        ]
      },
      "sale_insight": {
        "ad_id": "23851172049950328",
        "date": "2022-10-23T18:54:35",
        "revenue": 500,
        "count": 1,
        "roas": 3,
        "cvr": 2.04,
        "cvr_cost": 1
      }
    }
  ],
  "total_count": 0,
  "offset": 0,
  "limit": 0
}

Get Campaign

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'

Path Parameters

Name	Type	Description
campaign_id*	string
app_id*	string
client_id*	string

200: OK

{
  "id": "23851172049950328",
  "ad_account_id": "174816537731874",
  "ad_account": {},
  "name": "Spot image",
  "status": "ACTIVE",
  "start_time": "2022-11-01T10:05:08+01:00",
  "stop_time": "2022-11-30T14:05:08+01:00",
  "page": {},
  "insight": {
    "campaign_id": "23851172049950328",
    "date": "2023-02-28T08:01:15.667000",
    "clicks": 1234,
    "cpc": 0.3,
    "cpm": 3.4,
    "ctr": 1.4,
    "impressions": 6789,
    "spend": 123.45,
    "currency": "EUR",
    "sessions": 6789,
    "cost_per_session": 0.45,
    "cvr_clicks_to_sessions": 0.45,
    "unique_users": 5999,
    "cost_per_unique_user": 0.45,
    "cvr_clicks_to_unique_users": 0.45,
    "engaged": 5999,
    "cost_per_engagement": 0.45,
    "cvr_unique_users_to_engaged": 0.45,
    "converted": 5999,
    "cost_per_conversions": 0.45,
    "cvr_unique_users_to_converted": 0.45,
    "events": {
      "conversation": 2,
      "keyword": 0
    },
    "keywords": [
      {
        "keyword": "Product ordered",
        "events": 7,
        "cvr": 1.23
      }
    ]
  },
  "sale_insight": {
    "ad_id": "23851172049950328",
    "date": "2022-10-23T18:54:35",
    "revenue": 500,
    "count": 1,
    "roas": 3,
    "cvr": 2.04,
    "cvr_cost": 1
  }
}

Get Campaign Insights

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'

Path Parameters

Name	Type	Description
ad_account_id*	string
app_id*	string
client_id*	string

200: OK

{
  "data": [
    {
      "id": "23851172049950328",
      "ad_account_id": "174816537731874",
      "ad_account": {
        "name": "360dialog.com - Ad-Account",
        "currency": "EUR"
      },
      "name": "Spot image",
      "status": "ACTIVE",
      "start_time": "2022-11-01T10:05:08+01:00",
      "stop_time": "2022-11-30T14:05:08+01:00",
      "page": {
        "id": "460293477343848"
      },
      "insight": {
        "campaign_id": "23851172049950328",
        "date": "2023-02-28T08:01:15.667000",
        "clicks": 1234,
        "cpc": 0.3,
        "cpm": 3.4,
        "ctr": 1.4,
        "impressions": 6789,
        "spend": 123.45,
        "currency": "EUR",
        "sessions": 6789,
        "cost_per_session": 0.45,
        "cvr_clicks_to_sessions": 0.45,
        "unique_users": 5999,
        "cost_per_unique_user": 0.45,
        "cvr_clicks_to_unique_users": 0.45,
        "engaged": 5999,
        "cost_per_engagement": 0.45,
        "cvr_unique_users_to_engaged": 0.45,
        "converted": 5999,
        "cost_per_conversions": 0.45,
        "cvr_unique_users_to_converted": 0.45,
        "events": {
          "conversation": 2,
          "keyword": 0
        },
        "keywords": [
          {
            "keyword": "Product ordered",
            "events": 7,
            "cvr": 1.23
          }
        ]
      },
      "sale_insight": {
        "ad_id": "23851172049950328",
        "date": "2022-10-23T18:54:35",
        "revenue": 500,
        "count": 1,
        "roas": 3,
        "cvr": 2.04,
        "cvr_cost": 1
      }
    }
  ],
  "total_count": 0,
  "offset": 0,
  "limit": 0
}

Refresh Campaigns Insights

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'

Path Parameters

Name	Type	Description
ad_account_id*	string
app_id*	string
client_id*	string

200: OK

{
  "success": true
}

Refresh Campaign Insights

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'

Path Parameters

Name	Type	Description
campaign_id*	string
app_id*	string
client_id*	string

200: OK

{
  "success": true
}

Events

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.

Event Type
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.

Create converted event

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"

Path Parameters

Name	Type	Description
app_id*	string
client_id*	string

Request Body

Name	Type	Description
campaign_id*	string
type*	string	Allowed values: button button_reply conversation converted engagement keyword link list list_reply
type_value	string
type_id	string

200: OK

{
  "success": true
}

Get Events Types

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'

Path Parameters

Name	Type	Description
app_id*	string
client_id*	string

Query Parameters

Name	Type	Description
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

200: OK

[
  {
    "name": "string",
    "value": "button" 
  }
]

//Possible values:
//button
//button_reply
//conversation
//converted
//engagement
//keyword
//link
//list
//list_reply

Get Events

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'

Path Parameters

Name	Type	Description
app_id*	string
client_id*	string

Query Parameters

Name	Type	Description
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

200: OK

{
  "data": [
    {
      "id": "ABGGeRKYlEBvAgo-sNqg6B4gkcj8",
      "app_id": "72822",
      "ad_id": "23851172049950328",
      "campaign_id": "23851172049950328",
      "phone": "123456789",
      "type": "conversation", //event type
      "type_id": "63c14b9487dd821c0be8a0b6",
      "type_value": "product ordered", //converted event
      "date": "2022-10-23T18:54:35",
      "conversation_id": "12453ewa",
      "conversation_expire_time": "2022-12-01T00:05:08+01:00",
      "source_id": "So2315r13"
    }
  ],
  "total_count": 0,
  "offset": 0,
  "limit": 0
}

Export Events

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'

Path Parameters

Name	Type	Description
app_id*	string
client_id*	string

Query Parameters

Name	Type	Description
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

200: OK

Get Event Stats

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'

Path Parameters

Name	Type	Description
app_id*	string
client_id*	string

200: OK

{
  "sessions_num": 0,
  "events_num": 0
}

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 Events Groups

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'

Path Parameters

Name	Type	Description
app_id*	string
client_id*	string

Query Parameters

Name	Type	Description
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

200: OK

{
  "data": [
    {
      "app_id": "72822",
      "ad_id": "23851172049950328",
      "campaign_id": "23851172049950328",
      "type": "conversation",
      "type_id": "63c14b9487dd821c0be8a0b6",
      "type_value": "product ordered",
      "status": "active",
      "first_event": "2022-11-20T14:05:08+01:00",
      "last_event": "2022-11-30T14:05:08+01:00",
      "last_update": "2022-12-01T00:05:08+01:00",
      "events": 10,
      "cvr": 2.04
    }
  ],
  "total_count": 0,
  "offset": 0,
  "limit": 0
}

Creating an Ad Campaign

Facebook Account

Get Facebook Accounts

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" }'

Path Parameters

Name	Type	Description
app_id*	string
client_id*	string

200: OK

[
  {
    "id": "100090613944471",
    "name": "Mike Bush",
    "client_id": "bbxYayFhCL",
    "permanent_token": "63c14b9487dd821c0be8a0b6",
    "ad_accounts": [
      {
        "id": "174816537731874",
        "name": "360dialog.com - Ad-Account - 2",
        "currency": "EUR"
      }
    ]
  }
]

Create Facebook Account

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" }'

Path Parameters

Name	Type	Description
client_id*	string
app_id*	string

Request Body

Name	Type	Description
temporary_token*	string

200: OK

{
  "success": true
}

Get Facebook Ad Accounts

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'

Path Parameters

Name	Type	Description
client_id*	string
app_id*	string
facebook_account_id*	string

200: OK

[]

Ad Campaign

Create Facebook Ad Campaign

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" }'

Path Parameters

Name	Type	Description
app_id*	string
client_id*	string
facebook_ad_account_id*	string
facebook_account_id*	string

Request Body

Name	Type	Description
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

200: OK

{
  "campaign_id": "23853062207880328",
  "adset_id": "43853062207880328",
  "ad_id": "53853062207880328"
}

Get Facebook Pages ID

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'

Path Parameters

Name	Type	Description
client_id*	string
app_id*	string
facebook_account_id*	string
facebook_ad_account_id*	string

200: OK

[
  {
    "id": "460293477343848",
    "name": "360dialog"
  }
]

Get Facebook Ad Images

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'

Path Parameters

Name	Type	Description
client_id*	string
app_id*	string
facebook_account_id*	string

200: OK

[
  {
    "name": "untitled.jpg",
    "hash": "a275aa36c7b2e6d0105bf683c55e7bd6",
    "url": "https://fb.com/untitled.jpg"
  }
]

Upload Image

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=

Path Parameters

Name	Type	Description
app_id*	string
client_id*	string
facebook_ad_account_id*	string
facebook_account_id*	string

Request Body

Name	Type	Description
img*	string

200: OK

{
  "image_hash": "a275aa36c7b2e6d0105bf683c55e7bd6"
}

Get Targeting Geolocations

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 '

Path Parameters

Name	Type	Description
client_id*	string
app_id*	string
facebook_account_id*	string
facebook_ad_account_id*	string

Query Parameters

Name	Type	Description
query*	string

200: OK

[
  {
    "name": "United States",
    "type": "country",
    "key": "US"
  }
]

Text-based Trackable Events (Keywords)

Get Keywords

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'

Path Parameters

Name	Type	Description
client_id*	string
app_id*	string

Query Parameters

Name	Type	Description
ad_id	string	Example: 23851172049950328
offset	integer
limit	integer
is_shared	boolean	Example: true
status	string	Allowed values: active archived

200: OK

{
  "data": [
    {
      "id": "63c14b9487dd821c0be8a0b6",
      "app_id": "72822",
      "ad_id": "23851172049950328",
      "keyword": "product ordered",
      "status": "active",
      "first_event": "2022-11-20T14:05:08+01:00",
      "last_event": "2022-11-30T14:05:08+01:00",
      "last_update": "2022-12-01T00:05:08+01:00",
      "events": 10,
      "cvr": 2.04,
      "is_shared": false
    }
  ],
  "total_count": 0,
  "offset": 0,
  "limit": 0
}

Create Keyword

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" }'

Path Parameters

Name	Type	Description
client_id*	string
app_id*	string

Query Parameters

Name	Type	Description
ad_id	string	Example: 23851172049950328

Request Body

Name	Type	Description
keyword*	string	Example: Product ordered

200: OK

{
  "success": true
}

Get Keyword

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'

Path Parameters

Name	Type	Description
app_id*	string
client_id*	string
keyword_id*	string

Query Parameters

Name	Type	Description
ad_id	string
is_shared	boolean

200: OK

{
  "id": "63c14b9487dd821c0be8a0b6",
  "app_id": "72822",
  "ad_id": "23851172049950328",
  "keyword": "product ordered",
  "status": "active",
  "first_event": "2022-11-20T14:05:08+01:00",
  "last_event": "2022-11-30T14:05:08+01:00",
  "last_update": "2022-12-01T00:05:08+01:00",
  "events": 0,
  "cvr": 0,
  "is_shared": false
}

Delete Keyword

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'

Path Parameters

Name	Type	Description
app_id*	string
keyword_id*	string
client_id*	string

Query Parameters

Name	Type	Description
ad_id	string
delete	boleean

200: OK

{
  "success": true
}

Update Keyword

PATCH [signals-base-url]/v1/clients/{client_id}/apps/{app_id}/keywords/{keyword_id}

Disable existing keyword and create a new one

Path Parameters

Name	Type	Description
app_id*	string
keyword_id*	string
client_id*	string

Query Parameters

Name	Type	Description
ad_id	string

Request Body

Name	Type	Description
keyword*	string	Example: Product ordered

200: OK

{
  "success": true
}

Create Shared Keyword

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.

Path Parameters

Name	Type	Description
client_id*	string
app_id*	string

Request Body

Name	Type	Description
keyword*	string	Example: Product ordered

200: OK

{
  "success": true
}

Sales

Create Sale

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 }'

Path Parameters

Name	Type	Description
app_id*	string
client_id*	string

Request Body

Name	Type	Description
phone*	string	Example: 123456789
amount*	number	Example: 100

200: OK

{
  "success": true
}

Get Sale Insights

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'

Path Parameters

Name	Type	Description
ad_id*	string
client_id*	string
app_id*	string

Query Parameters

Name	Type	Description
date_from*	string
date_to*	string

200: OK

[
  {
    "ad_id": "23851172049950328",
    "date": "2022-10-23T18:54:35",
    "revenue": 500,
    "count": 1,
    "roas": 3,
    "cvr": 2.04,
    "cvr_cost": 1
  }
]

Receive instant notifications

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 list of Signals

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'

Path Parameters

Name	Type	Description
ad_id*	string
client_id*	string
app_id*	string

200: OK

[
  {
    "app_id": "100090613944471",
    "ad_id": "23851172049950328",
    "keyword_id": "63c14b9487dd821c0be8a0b6",
    "event_type": "conversation",
    "url": "https://example.com"
  }
]

Set Signal Of Ad

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'

Path Parameters

Name	Type	Description
ad_id*	string
client_id*	string
app_id*	string

Request Body

Name	Type	Description
url	string <uri>	>= 1 characters | <= 65536 characters

200: OK

Get Signal Of Ad

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 '

Path Parameters

Name	Type	Description
ad_id*	string
client_id*	string
app_id*	string

200: OK

{
  "url": "https://example.com"
}

Set Signal of Keyword

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" }'

Path Parameters

Name	Type	Description
keyword_id*	string
client_id*	string
app_id*	string
ad_id*	string

Request Body

Name	Type	Description
url	string<url>

200: OK

Get Signal Of Keyword

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'

Path Parameters

Name	Type	Description
ad_id*	string
client_id*	string
app_id*	string
keyword_id*	string

200: OK

{
  "url": "https://example.com"
}

Set Signal of Event

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" }'

Path Parameters

Name	Type	Description
client_id*	String
app_id*	String
ad_id*	String
event_type*	str	Allowed value: session_start

Get Signal of Event

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" }'

Path Parameters

Name	Type	Description
client_id*	string
app_id*	string
ad_id*	string
event_type*	string	Allowed value: session_start

200: OK

{
  "url": "https://example.com"
}