Send Campaigns
Last updated
Last updated
Reach out to your Account Manager for details on how to set up a campaign/flow.
Important: Currently custom parameters like variables, custom images and URL suffix are only supported on the first message of a campaign flow. This is on the roadmap for Q4 2023.
The Connectly Message Service API allows you to send a sequence of messages (bot/flow) from one API call by adding the campaignName parameter.
Your account manager can help you with the flow and share the campaign name that you invoke in the API request.
Here are the steps on how to find the campaignName parameter on your own.
Go to the inbox https://inbox.connectly.ai
Click on the Flow Builder
Create New Campaign
Go through all the steps and send campaign to yourself (WhatsApp phone number)
Verify that the campaign was sent succesfully
Go back to Flow Builder
Select Resend or Edit a Campaign
Find your campaign and copy the name of it
Use it in the campaignName in Initiate Campaign Sendout
You can use this endpoint to initiate a sendout of one or more campaigns.
Each entry in the body contains information about the campaign and its recipient.
Ensure each entry in the "entries" array contains valid and unique combinations of client and campaignName/campaignVersion. (see Multiple campaigns if your intent is to broadcast multiple sendouts from the same API call)
Use the "variables" field to customize campaign content or behavior.
Campaigns must have been finalized from the Connectly UI for successful execution.
[Alpha] Schedule individual (or all) entries for the future using the "scheduledAt" field, adhering to the ISO 8601 format.
This example represents the minimal setup of campaign entry with only the required fields for a campaign that doesn't use any variables.
Explanation:
client: The identifier of the customer who will receive the campaign (required).
campaignName: The identifier of the campaign this entry is part of (required).
This example includes variables for customizing the campaign experience per client. Variables are configured for each campaign from the Connectly UI.
Explanation:
client: The identifier of the customer who will receive the campaign (required).
campaignName: The identifier of the campaign this entry is part of (required).
variables: JSON object describing flow variables and substituted values.
By default, this API is not allowed to send a campaign to a user more than once. But if you really need to send a campaign to the same group of customers more than once, you can specify the following option.
With this option set, the campaign will be sent to the group of customers even they have received the same campaign before.
As above request payload shows, in order to let the client receive the campaign again, we can't have campaignVersion parameter, otherwise the recipient will be skipped if it has received the campaign before.
Note that even with this option set, there is a restriction that you can't use the API twice in one hour. Therefore, if you want to use the API with this option on, please also set all entries in one API request.
This example demonstrates the inclusion of multiple campaigns within a single API request. The API groups campaign entries by the requested campaign name and optionally the campaign version to utilize different sendouts for each combination.
Each campaign entry object should be using a consistent structure, encompassing key details for the campaign configuration:
Sendout A:
Campaign Name: "campaign_A"
Campaign Version: "v1.0"
All entries using the above information will be sent as part of the sendout corresponding to the version "v1.0" of campaign A.
Sendout B:
Campaign Name: "campaign_A"
All entries using the above information will be sent as part of a new sendout or the latest active sendout on campaign A.
Sendout C:
Campaign Name: "campaign_B"
Campaign Version: v1.0
All entries using the above information will be sent as part of the sendout corresponding to the version "v1.0" of campaign B
The array structure allows for the inclusion of various campaigns in a cohesive and organized manner within a single API request.
thin a single API request.
Explanation:
Entry for Campaign A:
client: The identifier of the customer who will receive the campaign.
campaignName: The identifier of the campaign (campaign_A).
campaignVersion: Identifier of the campaign version (v1.0).
variables: JSON object describing flow variables and substituted values (key1, key2).
Entry for Campaign B:
client: The identifier of the customer who will receive the campaign.
campaignName: The identifier of the campaign (campaign_A).
variables: JSON object describing flow variables and substituted values (key1, key2).
Entry for Campaign C:
client: The identifier of the customer who will receive the campaign.
campaignName: The identifier of the campaign (campaign_B).
variables: JSON object describing flow variables and substituted values (Date, Name, Price).
campaignVersion: Identifier of the campaign version (v1.0).
The API response provides information about the status of a campaign and related details. The response is in JSON format and includes key data points related to the campaign.
The response consists of a JSON object with a "data" array containing campaign information. Below is a breakdown of the key fields:
campaignId: Unique identifier for the campaign.
campaignName: The name of the campaign (e.g., "campaign_test").
campaignVersion: Version identifier for the campaign.
sendoutId: Unique identifier for the sendout associated with the campaign.
status: The status of the campaign (e.g., "updated", "created").
acceptedCount: Number of accepted responses.
rejectedCount: Number of rejected responses.
error: An optional field indicating any errors encountered during the campaign processing. It is set to null if no errors occurred.
Examples:
Simple body request:
Response:
If you send the campaign again the status shows as Updated:
If you send body without entries:
The response its going to be empty too:
If you specify a wrong campaign name:
You will get the error detail:
If you specify a wrong campaign version:
You will get the error detail:
If you don't specify all the variables:
You will get the error detail:
To ensure fair usage and maintain service stability, we have implemented rate limiting for above APIs. This endpoint is limited to 200 requests per second. If the limit is exceeded, the API will return a 429 Too Many Requests response.
API to send campaigns to multiple recipients.
List of campaign entries.
Options for sending campaigns.
Success: Response contains data including a report of the generated sendouts.
List of reports for the executed sendouts.