Connectly Documentation
  • ๐Ÿ‘‹Welcome to Connectly.ai
  • ๐Ÿš€Quick Start
    • Prerequisites
    • Authentication
    • Send WhatsApp template message
    • Send WhatsApp session message
  • ๐Ÿ“ฃCampaigns
    • Campaign Sendout
      • Send Campaigns
  • ๐Ÿค–Sofia AI
    • How to use Sofia AI?
    • Sofia AI API
      • Reference
        • Core Concepts
        • sales_assistant_v2/invoke/v1
  • ๐Ÿ“ฑMessage API
    • Message Service API
      • MessageService
        • Send template message
        • Send session message
      • Error codes
    • Webhook API
      • WebhookService
        • Create a webhook registration by event topic
        • Update an existing webhook registration by event topic
        • Get webhook registrations for business
        • Delete a webhook registration for business
      • Webhook Payload
        • Delivery Status Error Codes
        • Payload Media Types
  • ๐Ÿค–Business Management
    • Business Management API
      • Template Management
        • Create a template
        • Get templates
      • Quality Signals
  • ๐Ÿ“ฑIntegrations
    • Integrations
      • WebEngage Integration
      • Message your customers on Zendesk through Connectly
      • Message your customer on Intercom through Connectly
    • [Alpha] Moengage
      • MessageService
        • Send Campaign via API
  • ๐Ÿ“ŠAnalytics
    • Analytics
      • [Alpha] Campaign report
      • Reports API
        • Webhooks configuration
  • ๐Ÿ‘€FAQ
  • Migrating WhatsApp Accounts
  • How to use time delay?
Powered by GitBook
On this page
  1. Campaigns
  2. Campaign Sendout

Send Campaigns

PreviousCampaign SendoutNextHow to use Sofia AI?

Last updated 8 days ago

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

  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.

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.

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.

{
  "client": "+16505551236",
  "campaignName": "campaign_basic"
}

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.

{
  "client": "+16505551237",
  "campaignName": "campaign_with_variables",
  "variables": {
    "username": "JaneDoe",
    "product": "Smart Watch"
  }
}

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.

{
  "options": {
    "if_duplicate_check_unspecified": "allow_multiple"
  },
  "entries": [
    {
      "client": "+14155558234",
      "campaignName": "campaign",
      "variables": {"key": "value"}
    }
  ]
}

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.

"entries": [
    {
      "client": "+14155558234",
      "campaignName": "campaign_A",
      "campaignVersion": "v1.0",
      "variables": {"key1": "value1", "key2": "value2"},
    },
    {
      "client": "+14155559345",
      "campaignName": "campaign_A",
      "variables": {"key1": "value3", "key2": "value4"},
    },
    {
      "client": "+14155550456",
      "campaignName": "campaign_B",
      "campaignVersion": "v1.0",
      "variables": {"Date": "value5", "Name": "value6","Price":"value7"},
    }
  ]

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:

{
    "entries": [
        {
            "client": "+123456789",
            "campaignName": "campaign_test",
            "variables": {
                "client": "pablo",
                "name": "test2"
            }
        }
    ]
}

Response:

{
    "data": [
        {
            "campaignId": "2963626c-90ea-43e5-9b66-4ce70f003fe3",
            "campaignName": "campaignv3",
            "campaignVersion": "018c5c51-8631-28b5-3c81-b70ecf14faef",
            "sendoutId": "183e801b-1438-4177-b283-909135096e69",
            "status": "created",
            "acceptedCount": 1,
            "rejectedCount": 0,
            "error": null
        }
    ]
}

If you send the campaign again the status shows as Updated:

{
    "data": [
        {
            "campaignId": "2963626c-90ea-43e5-9b66-4ce70f003fe3",
            "campaignName": "campaignv3",
            "campaignVersion": "018c5c51-8631-28b5-3c81-b70ecf14faef",
            "sendoutId": "183e801b-1438-4177-b283-909135096e69",
            "status": "updated",
            "acceptedCount": 1,
            "rejectedCount": 0,
            "error": null
        }
    ]
}

If you send body without entries:

{
    "client": "+123456789",
    "campaignName": "campaignv3",
    "variables": {
        "client": "pablo",
        "name": "test2"
    },
    "campaignVersion": "018c4a55-f3df-580c-1629-602f3b14d190"
}

The response its going to be empty too:

{
    "data": []
}

If you specify a wrong campaign name:

{
    "entries": [
        {
            "client": "+123456789",
            "campaignName": "campaรฑa",
            "variables": {
                "client": "pablo",
                "name": "test2"
            }
        }
    ]
}

You will get the error detail:

{
    "data": [
        {
            "campaignId": null,
            "campaignName": "campaรฑa",
            "campaignVersion": null,
            "sendoutId": null,
            "status": "error",
            "acceptedCount": 0,
            "rejectedCount": 1,
            "error": {
                "message": "Campaign not found",
                "type": "ERROR_TYPE_NOT_FOUND",
                "code": "ERROR_CODE_CAMPAIGN_NOT_FOUND",
                "userTitle": "Campaign not found",
                "userMessage": "Please review the campaign name and/or campaign id."
            }
        }
    ]
}

If you specify a wrong campaign version:

{
    "entries": [
        {
            "client": "+123456789",
            "campaignName": "campaignv3",
            "variables": {
                "client": "pablo",
                "name": "test2"
            },
            "campaignVersion": "018c4a55-f3df-580c-1629-602f3b14d190"
        }
    ]
}

You will get the error detail:

{
    "data": [
        {
            "campaignId": "2963626c-90ea-43e5-9b66-4ce70f003fe3",
            "campaignName": "campaignv3",
            "campaignVersion": "018c4a55-f3df-580c-1629-602f3b14d190",
            "sendoutId": null,
            "status": "error",
            "acceptedCount": 0,
            "rejectedCount": 1,
            "error": {
                "message": "Campaign version not found",
                "type": "ERROR_TYPE_NOT_FOUND",
                "code": "ERROR_CODE_CAMPAIGN_VERSION_NOT_FOUND",
                "userTitle": "Campaign version not found",
                "userMessage": "Please review the campaign version."
            }
        }
    ]
}

If you don't specify all the variables:

{
    "entries": [
        {
            "client": "+123456789",
            "campaignName": "campaignv3",
            "variables": {
                "client": "pablo"
            }
        }
    ]
}

You will get the error detail:

{
    "data": [
        {
            "campaignId": "2963626c-90ea-43e5-9b66-4ce70f003fe3",
            "campaignName": "campaignv3",
            "campaignVersion": "018c5c51-8631-28b5-3c81-b70ecf14faef",
            "sendoutId": "183e801b-1438-4177-b283-909135096e69",
            "status": "error",
            "acceptedCount": 0,
            "rejectedCount": 1,
            "error": {
                "message": "Campaign entry is invalid",
                "type": "ERROR_TYPE_INVALID_REQUEST",
                "code": "ERROR_CODE_CAMPAIGN_ENTRY_INVALID",
                "userTitle": "Campaign entry is invalid",
                "userMessage": "Please check the inputs to the campaign entry."
            }
        }
    ]
}

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.

๐Ÿ“ฃ
https://inbox.connectly.ai
  • Create a Campaign in Flow Builder
  • Create your campaign in the inbox
  • Initiate Campaign Sendout
  • POST/v1/businesses/{businessId}/send/campaigns
  • Campaign Entry
  • Entry Tips
  • Basic entry
  • Entry with variables
  • Options
  • Multiple Campaigns
  • Response
  • Rate Limiting
post

API to send campaigns to multiple recipients.

Authorizations
Path parameters
businessIdanyRequired
Body
Responses
200
Success: Response contains data including a report of the generated sendouts.
application/json
400
Error: Request was malformed.
application/json
401
Error: Request presented invalid credentials.
application/json
404
Error: Request attempted to use a non existing campaign.
application/json
409
Error: Request attempted to use a campaign in the wrong state.
application/json
500
Error: There was an internal server error.
application/json
default
An unexpected error response.
application/json
post
POST /v1/businesses/{businessId}/send/campaigns HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 451

{
  "entries": [
    {
      "client": "+16505551234",
      "campaignName": "campaign 2023 11 17"
    },
    {
      "client": "+16505551235",
      "campaignName": "campaign 2023 11 18",
      "variables": {
        "customername": "John Doe",
        "product": "Sofia AI"
      }
    },
    {
      "client": "+16505551235",
      "campaignName": "campaign 2023 11 18",
      "variables": {
        "customername": "John Doe",
        "product": "Sofia AI"
      },
      "campaignVersion": "v1.0"
    }
  ],
  "options": {
    "if_version_unspecified": "reuse_last_active",
    "if_duplicate_check_unspecified": "allow_one"
  }
}
{
  "data": [
    {
      "campaignId": "10f041c3-25b4-4f3b-adb0-889d98476e7a",
      "campaignName": "local 2023 29",
      "campaignVersion": "v1.0",
      "sendoutId": "0d300213-1889-448d-b1e5-7503fe4be68f",
      "status": "created",
      "acceptedCount": 1,
      "rejectedCount": 0,
      "error": null
    },
    {
      "campaignId": "10f041c3-25b4-4f3b-adb0-889d98476e7a",
      "campaignName": "local 2023 29",
      "campaignVersion": "v1.0",
      "sendoutId": "0d300213-1889-448d-b1e5-7503fe4be68f",
      "status": "error",
      "acceptedCount": 1,
      "rejectedCount": 0,
      "error": null
    },
    {
      "campaignId": "10f041c3-25b4-4f3b-adb0-889d98476e7a",
      "campaignName": "local 2023 29",
      "campaignVersion": "v1.1",
      "sendoutId": "0d300213-1889-448d-b1e5-7503fe4be68f",
      "status": "error",
      "acceptedCount": 0,
      "rejectedCount": 1,
      "error": {
        "message": "Campaign entry is invalid",
        "type": "ERROR_TYPE_INVALID_REQUEST",
        "code": "ERROR_CODE_CAMPAIGN_ENTRY_INVALID",
        "userTitle": "Campaign entry is invalid",
        "userMessage": "Please check the inputs to the campaign entry."
      }
    }
  ]
}