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.
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.
Success: Response contains data including a report of the generated sendouts.
List of reports for the executed sendouts.