Ads
Create messaging ad
Starts a draft click-to-message ad campaign (campaign/ad set/ad) for the given audience and creative. Use ads.publishCampaign to publish it once ready.
POST
/
v1
/
ads
/
campaigns
Create messaging ad
curl --request POST \
--url https://app.chatbotx.io/api/v1/ads/campaigns \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"integrationId": "<string>",
"adAccountId": "<string>",
"name": "<string>",
"campaign": {
"specialAdCategories": [],
"specialAdCategoryCountry": [
"<string>"
]
},
"adSet": {
"dailyBudgetMinorUnits": 0,
"targeting": {
"countries": [
"<string>"
],
"ageMin": 39,
"ageMax": 39,
"genders": [
1
],
"locales": [
0
]
},
"startTime": "<string>",
"endTime": "<string>"
},
"creative": {
"media": {
"kind": "image",
"imageKey": "<string>",
"fileId": "<string>",
"link": "<string>",
"imageMimeType": "<string>",
"imageFileName": "<string>",
"message": "<string>",
"headline": "<string>",
"description": "<string>",
"caption": "<string>"
},
"welcomeMessage": {
"type": "default"
}
},
"whatsappPageIntegrationId": "<string>"
}
'import requests
url = "https://app.chatbotx.io/api/v1/ads/campaigns"
payload = {
"integrationId": "<string>",
"adAccountId": "<string>",
"name": "<string>",
"campaign": {
"specialAdCategories": [],
"specialAdCategoryCountry": ["<string>"]
},
"adSet": {
"dailyBudgetMinorUnits": 0,
"targeting": {
"countries": ["<string>"],
"ageMin": 39,
"ageMax": 39,
"genders": [1],
"locales": [0]
},
"startTime": "<string>",
"endTime": "<string>"
},
"creative": {
"media": {
"kind": "image",
"imageKey": "<string>",
"fileId": "<string>",
"link": "<string>",
"imageMimeType": "<string>",
"imageFileName": "<string>",
"message": "<string>",
"headline": "<string>",
"description": "<string>",
"caption": "<string>"
},
"welcomeMessage": { "type": "default" }
},
"whatsappPageIntegrationId": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
integrationId: '<string>',
adAccountId: '<string>',
name: '<string>',
campaign: {specialAdCategories: [], specialAdCategoryCountry: ['<string>']},
adSet: {
dailyBudgetMinorUnits: 0,
targeting: {countries: ['<string>'], ageMin: 39, ageMax: 39, genders: [1], locales: [0]},
startTime: '<string>',
endTime: '<string>'
},
creative: {
media: {
kind: 'image',
imageKey: '<string>',
fileId: '<string>',
link: '<string>',
imageMimeType: '<string>',
imageFileName: '<string>',
message: '<string>',
headline: '<string>',
description: '<string>',
caption: '<string>'
},
welcomeMessage: {type: 'default'}
},
whatsappPageIntegrationId: '<string>'
})
};
fetch('https://app.chatbotx.io/api/v1/ads/campaigns', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.chatbotx.io/api/v1/ads/campaigns",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'integrationId' => '<string>',
'adAccountId' => '<string>',
'name' => '<string>',
'campaign' => [
'specialAdCategories' => [
],
'specialAdCategoryCountry' => [
'<string>'
]
],
'adSet' => [
'dailyBudgetMinorUnits' => 0,
'targeting' => [
'countries' => [
'<string>'
],
'ageMin' => 39,
'ageMax' => 39,
'genders' => [
1
],
'locales' => [
0
]
],
'startTime' => '<string>',
'endTime' => '<string>'
],
'creative' => [
'media' => [
'kind' => 'image',
'imageKey' => '<string>',
'fileId' => '<string>',
'link' => '<string>',
'imageMimeType' => '<string>',
'imageFileName' => '<string>',
'message' => '<string>',
'headline' => '<string>',
'description' => '<string>',
'caption' => '<string>'
],
'welcomeMessage' => [
'type' => 'default'
]
],
'whatsappPageIntegrationId' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.chatbotx.io/api/v1/ads/campaigns"
payload := strings.NewReader("{\n \"integrationId\": \"<string>\",\n \"adAccountId\": \"<string>\",\n \"name\": \"<string>\",\n \"campaign\": {\n \"specialAdCategories\": [],\n \"specialAdCategoryCountry\": [\n \"<string>\"\n ]\n },\n \"adSet\": {\n \"dailyBudgetMinorUnits\": 0,\n \"targeting\": {\n \"countries\": [\n \"<string>\"\n ],\n \"ageMin\": 39,\n \"ageMax\": 39,\n \"genders\": [\n 1\n ],\n \"locales\": [\n 0\n ]\n },\n \"startTime\": \"<string>\",\n \"endTime\": \"<string>\"\n },\n \"creative\": {\n \"media\": {\n \"kind\": \"image\",\n \"imageKey\": \"<string>\",\n \"fileId\": \"<string>\",\n \"link\": \"<string>\",\n \"imageMimeType\": \"<string>\",\n \"imageFileName\": \"<string>\",\n \"message\": \"<string>\",\n \"headline\": \"<string>\",\n \"description\": \"<string>\",\n \"caption\": \"<string>\"\n },\n \"welcomeMessage\": {\n \"type\": \"default\"\n }\n },\n \"whatsappPageIntegrationId\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.chatbotx.io/api/v1/ads/campaigns")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"integrationId\": \"<string>\",\n \"adAccountId\": \"<string>\",\n \"name\": \"<string>\",\n \"campaign\": {\n \"specialAdCategories\": [],\n \"specialAdCategoryCountry\": [\n \"<string>\"\n ]\n },\n \"adSet\": {\n \"dailyBudgetMinorUnits\": 0,\n \"targeting\": {\n \"countries\": [\n \"<string>\"\n ],\n \"ageMin\": 39,\n \"ageMax\": 39,\n \"genders\": [\n 1\n ],\n \"locales\": [\n 0\n ]\n },\n \"startTime\": \"<string>\",\n \"endTime\": \"<string>\"\n },\n \"creative\": {\n \"media\": {\n \"kind\": \"image\",\n \"imageKey\": \"<string>\",\n \"fileId\": \"<string>\",\n \"link\": \"<string>\",\n \"imageMimeType\": \"<string>\",\n \"imageFileName\": \"<string>\",\n \"message\": \"<string>\",\n \"headline\": \"<string>\",\n \"description\": \"<string>\",\n \"caption\": \"<string>\"\n },\n \"welcomeMessage\": {\n \"type\": \"default\"\n }\n },\n \"whatsappPageIntegrationId\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.chatbotx.io/api/v1/ads/campaigns")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"integrationId\": \"<string>\",\n \"adAccountId\": \"<string>\",\n \"name\": \"<string>\",\n \"campaign\": {\n \"specialAdCategories\": [],\n \"specialAdCategoryCountry\": [\n \"<string>\"\n ]\n },\n \"adSet\": {\n \"dailyBudgetMinorUnits\": 0,\n \"targeting\": {\n \"countries\": [\n \"<string>\"\n ],\n \"ageMin\": 39,\n \"ageMax\": 39,\n \"genders\": [\n 1\n ],\n \"locales\": [\n 0\n ]\n },\n \"startTime\": \"<string>\",\n \"endTime\": \"<string>\"\n },\n \"creative\": {\n \"media\": {\n \"kind\": \"image\",\n \"imageKey\": \"<string>\",\n \"fileId\": \"<string>\",\n \"link\": \"<string>\",\n \"imageMimeType\": \"<string>\",\n \"imageFileName\": \"<string>\",\n \"message\": \"<string>\",\n \"headline\": \"<string>\",\n \"description\": \"<string>\",\n \"caption\": \"<string>\"\n },\n \"welcomeMessage\": {\n \"type\": \"default\"\n }\n },\n \"whatsappPageIntegrationId\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"channel": "<string>",
"adAccountId": "<string>",
"name": "<string>",
"createState": "<string>",
"publishState": "<string>",
"metaCampaignId": "<string>",
"metaAdSetId": "<string>",
"metaAdCreativeId": "<string>",
"metaAdId": "<string>",
"lastError": "<string>",
"cleanupError": "<string>",
"effectiveStatus": "<string>",
"createdAt": "2023-11-07T05:31:56Z"
}{
"defined": true,
"code": "businessError",
"status": 400,
"message": "An error occurred while processing your request",
"data": "<unknown>"
}{
"defined": true,
"code": "UNAUTHORIZED",
"status": 401,
"message": "Authentication required",
"data": "<unknown>"
}{
"defined": true,
"code": "FORBIDDEN",
"status": 403,
"message": "You do not have permission to perform this action",
"data": "<unknown>"
}{
"defined": true,
"code": "invalidRequestData",
"status": 422,
"message": "Input validation failed",
"data": {
"issues": [
{
"message": "<string>",
"path": [
"<string>"
]
}
]
}
}{
"defined": true,
"code": "tooManyRequests",
"status": 429,
"message": "Too many requests",
"data": "<unknown>"
}{
"defined": true,
"code": "INTERNAL_SERVER_ERROR",
"status": 500,
"message": "An unexpected error occurred",
"data": "<unknown>"
}Authorizations
bearerAuthdeveloperAccessTokentokenInSearchParams
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Channel to run the messaging ad on.
Available options:
messenger, instagram, whatsapp Channel integration id (numeric string).
Pattern:
^\d+$Meta ad account id (act_). Get it from ads.listCampaignAdAccounts.
Pattern:
^act_\d+$Campaign name.
Required string length:
1 - 120Campaign-level settings.
Show child attributes
Show child attributes
Ad set-level settings.
Show child attributes
Show child attributes
Ad creative settings.
Show child attributes
Show child attributes
Messenger page integration id, required when channel is whatsapp.
Pattern:
^\d+$Response
OK
Was this page helpful?
⌘I
Create messaging ad
curl --request POST \
--url https://app.chatbotx.io/api/v1/ads/campaigns \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"integrationId": "<string>",
"adAccountId": "<string>",
"name": "<string>",
"campaign": {
"specialAdCategories": [],
"specialAdCategoryCountry": [
"<string>"
]
},
"adSet": {
"dailyBudgetMinorUnits": 0,
"targeting": {
"countries": [
"<string>"
],
"ageMin": 39,
"ageMax": 39,
"genders": [
1
],
"locales": [
0
]
},
"startTime": "<string>",
"endTime": "<string>"
},
"creative": {
"media": {
"kind": "image",
"imageKey": "<string>",
"fileId": "<string>",
"link": "<string>",
"imageMimeType": "<string>",
"imageFileName": "<string>",
"message": "<string>",
"headline": "<string>",
"description": "<string>",
"caption": "<string>"
},
"welcomeMessage": {
"type": "default"
}
},
"whatsappPageIntegrationId": "<string>"
}
'import requests
url = "https://app.chatbotx.io/api/v1/ads/campaigns"
payload = {
"integrationId": "<string>",
"adAccountId": "<string>",
"name": "<string>",
"campaign": {
"specialAdCategories": [],
"specialAdCategoryCountry": ["<string>"]
},
"adSet": {
"dailyBudgetMinorUnits": 0,
"targeting": {
"countries": ["<string>"],
"ageMin": 39,
"ageMax": 39,
"genders": [1],
"locales": [0]
},
"startTime": "<string>",
"endTime": "<string>"
},
"creative": {
"media": {
"kind": "image",
"imageKey": "<string>",
"fileId": "<string>",
"link": "<string>",
"imageMimeType": "<string>",
"imageFileName": "<string>",
"message": "<string>",
"headline": "<string>",
"description": "<string>",
"caption": "<string>"
},
"welcomeMessage": { "type": "default" }
},
"whatsappPageIntegrationId": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
integrationId: '<string>',
adAccountId: '<string>',
name: '<string>',
campaign: {specialAdCategories: [], specialAdCategoryCountry: ['<string>']},
adSet: {
dailyBudgetMinorUnits: 0,
targeting: {countries: ['<string>'], ageMin: 39, ageMax: 39, genders: [1], locales: [0]},
startTime: '<string>',
endTime: '<string>'
},
creative: {
media: {
kind: 'image',
imageKey: '<string>',
fileId: '<string>',
link: '<string>',
imageMimeType: '<string>',
imageFileName: '<string>',
message: '<string>',
headline: '<string>',
description: '<string>',
caption: '<string>'
},
welcomeMessage: {type: 'default'}
},
whatsappPageIntegrationId: '<string>'
})
};
fetch('https://app.chatbotx.io/api/v1/ads/campaigns', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.chatbotx.io/api/v1/ads/campaigns",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'integrationId' => '<string>',
'adAccountId' => '<string>',
'name' => '<string>',
'campaign' => [
'specialAdCategories' => [
],
'specialAdCategoryCountry' => [
'<string>'
]
],
'adSet' => [
'dailyBudgetMinorUnits' => 0,
'targeting' => [
'countries' => [
'<string>'
],
'ageMin' => 39,
'ageMax' => 39,
'genders' => [
1
],
'locales' => [
0
]
],
'startTime' => '<string>',
'endTime' => '<string>'
],
'creative' => [
'media' => [
'kind' => 'image',
'imageKey' => '<string>',
'fileId' => '<string>',
'link' => '<string>',
'imageMimeType' => '<string>',
'imageFileName' => '<string>',
'message' => '<string>',
'headline' => '<string>',
'description' => '<string>',
'caption' => '<string>'
],
'welcomeMessage' => [
'type' => 'default'
]
],
'whatsappPageIntegrationId' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.chatbotx.io/api/v1/ads/campaigns"
payload := strings.NewReader("{\n \"integrationId\": \"<string>\",\n \"adAccountId\": \"<string>\",\n \"name\": \"<string>\",\n \"campaign\": {\n \"specialAdCategories\": [],\n \"specialAdCategoryCountry\": [\n \"<string>\"\n ]\n },\n \"adSet\": {\n \"dailyBudgetMinorUnits\": 0,\n \"targeting\": {\n \"countries\": [\n \"<string>\"\n ],\n \"ageMin\": 39,\n \"ageMax\": 39,\n \"genders\": [\n 1\n ],\n \"locales\": [\n 0\n ]\n },\n \"startTime\": \"<string>\",\n \"endTime\": \"<string>\"\n },\n \"creative\": {\n \"media\": {\n \"kind\": \"image\",\n \"imageKey\": \"<string>\",\n \"fileId\": \"<string>\",\n \"link\": \"<string>\",\n \"imageMimeType\": \"<string>\",\n \"imageFileName\": \"<string>\",\n \"message\": \"<string>\",\n \"headline\": \"<string>\",\n \"description\": \"<string>\",\n \"caption\": \"<string>\"\n },\n \"welcomeMessage\": {\n \"type\": \"default\"\n }\n },\n \"whatsappPageIntegrationId\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.chatbotx.io/api/v1/ads/campaigns")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"integrationId\": \"<string>\",\n \"adAccountId\": \"<string>\",\n \"name\": \"<string>\",\n \"campaign\": {\n \"specialAdCategories\": [],\n \"specialAdCategoryCountry\": [\n \"<string>\"\n ]\n },\n \"adSet\": {\n \"dailyBudgetMinorUnits\": 0,\n \"targeting\": {\n \"countries\": [\n \"<string>\"\n ],\n \"ageMin\": 39,\n \"ageMax\": 39,\n \"genders\": [\n 1\n ],\n \"locales\": [\n 0\n ]\n },\n \"startTime\": \"<string>\",\n \"endTime\": \"<string>\"\n },\n \"creative\": {\n \"media\": {\n \"kind\": \"image\",\n \"imageKey\": \"<string>\",\n \"fileId\": \"<string>\",\n \"link\": \"<string>\",\n \"imageMimeType\": \"<string>\",\n \"imageFileName\": \"<string>\",\n \"message\": \"<string>\",\n \"headline\": \"<string>\",\n \"description\": \"<string>\",\n \"caption\": \"<string>\"\n },\n \"welcomeMessage\": {\n \"type\": \"default\"\n }\n },\n \"whatsappPageIntegrationId\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.chatbotx.io/api/v1/ads/campaigns")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"integrationId\": \"<string>\",\n \"adAccountId\": \"<string>\",\n \"name\": \"<string>\",\n \"campaign\": {\n \"specialAdCategories\": [],\n \"specialAdCategoryCountry\": [\n \"<string>\"\n ]\n },\n \"adSet\": {\n \"dailyBudgetMinorUnits\": 0,\n \"targeting\": {\n \"countries\": [\n \"<string>\"\n ],\n \"ageMin\": 39,\n \"ageMax\": 39,\n \"genders\": [\n 1\n ],\n \"locales\": [\n 0\n ]\n },\n \"startTime\": \"<string>\",\n \"endTime\": \"<string>\"\n },\n \"creative\": {\n \"media\": {\n \"kind\": \"image\",\n \"imageKey\": \"<string>\",\n \"fileId\": \"<string>\",\n \"link\": \"<string>\",\n \"imageMimeType\": \"<string>\",\n \"imageFileName\": \"<string>\",\n \"message\": \"<string>\",\n \"headline\": \"<string>\",\n \"description\": \"<string>\",\n \"caption\": \"<string>\"\n },\n \"welcomeMessage\": {\n \"type\": \"default\"\n }\n },\n \"whatsappPageIntegrationId\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"channel": "<string>",
"adAccountId": "<string>",
"name": "<string>",
"createState": "<string>",
"publishState": "<string>",
"metaCampaignId": "<string>",
"metaAdSetId": "<string>",
"metaAdCreativeId": "<string>",
"metaAdId": "<string>",
"lastError": "<string>",
"cleanupError": "<string>",
"effectiveStatus": "<string>",
"createdAt": "2023-11-07T05:31:56Z"
}{
"defined": true,
"code": "businessError",
"status": 400,
"message": "An error occurred while processing your request",
"data": "<unknown>"
}{
"defined": true,
"code": "UNAUTHORIZED",
"status": 401,
"message": "Authentication required",
"data": "<unknown>"
}{
"defined": true,
"code": "FORBIDDEN",
"status": 403,
"message": "You do not have permission to perform this action",
"data": "<unknown>"
}{
"defined": true,
"code": "invalidRequestData",
"status": 422,
"message": "Input validation failed",
"data": {
"issues": [
{
"message": "<string>",
"path": [
"<string>"
]
}
]
}
}{
"defined": true,
"code": "tooManyRequests",
"status": 429,
"message": "Too many requests",
"data": "<unknown>"
}{
"defined": true,
"code": "INTERNAL_SERVER_ERROR",
"status": 500,
"message": "An unexpected error occurred",
"data": "<unknown>"
}