Ctrlk

Send Campaigns

Create a Campaign in Flow Builder

Reach out to your Account Manager for details on how to set up a campaign/flow.

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.

Create your campaign in the inbox

  1. Go to the inbox https://inbox.connectly.ai

  2. Click on Create new Campaign

  3. Create New Campaign

  4. Go through all the steps and send campaign to yourself (WhatsApp phone number)

  5. Verify that the campaign was sent succesfully

  6. Go back to Flow Builder

  7. Select Resend or Edit a Campaign

  8. Find your campaign and copy the name of it

  9. Use it in the campaignName in Initiate Campaign Sendout

{
     "sender": "+14151111234",
     "number": "+1(604) 585 2331",
     "templateName": "tempalte", 
     "language": "en",
     "parameters": [],
     "campaignName": "template123" 
}

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.

post

API to send campaigns to multiple recipients.

Authorizations
X-API-KeystringRequired

API key for authorization

Path parameters
businessIdanyRequired
Body
Responses
200

Success: Response contains data including a report of the generated sendouts.

application/json
post
/v1/businesses/{businessId}/send/campaigns

Campaign Entry

Entry Tips

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

The client field accepts an E.164 phone number or, for BSUID customers, the prefixed form bsuid:US.… (e.g. bsuid:US.13491208655302741918). Sending to phone-less (BSUID-only) customers is not available yet and currently returns a 400. See Business-scoped user IDs (BSUID).

Basic entry

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

Entry with variables

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.

Options

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 "if_duplicate_check_unspecified": "allow_multiple" set, the campaign will be sent to the group of customers even they have received the same campaign before.

Multiple Campaigns

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:

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

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

  3. 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:

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

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

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

Response

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:

Rate Limiting

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.

PreviousCampaign SendoutNextAssets API

Last updated