Campaign API Documentation

Overview

This document describes the Campaign API endpoints, request/response schemas, validation rules, error handling, and usage examples.

Endpoints

Create Campaign

Method: POST
Path: /v2/campaign/create
Headers: X-API-Key (required)
Request Body: CreateCampaignRequest
Response: CampaignResponse
Description: Create a new campaign.

Delete Campaign

Method: DELETE
Path: /v2/campaign/delete
Headers: X-API-Key (required)
Request Body: DeleteCampaignRequest
Response: CampaignResponse
Description: Delete a campaign by ID.

Get All Campaigns

Method: GET
Path: /v2/campaign/getAll
Headers: X-API-Key (required)
Query Params: resultSize (optional)
Response: JSON object (list of campaigns)
Description: Get all campaigns, optionally limited by result size.

Get Campaign Messages

Method: GET
Path: /v2/campaign/getCampMsgs
Headers: X-API-Key (required)
Query Params: campaignID (required), resultSize (optional)
Response: JSON object (list of messages)
Description: Get messages for a specific campaign.

Resend Failed Message

Method: POST
Path: /v2/campaign/resendMsg
Headers: X-API-Key (required)
Request Body: ResendCampaignMessageRequest
Response: JSON object
Description: Resend a failed campaign message by messageKey.

Update Scheduled Campaign

Method: PUT
Path: /v2/campaign/update
Headers: X-API-Key (required)
Request Body: UpdateCampaignRequest
Response: CampaignResponse
Description: Update a scheduled campaign's name or send time.
Important: Only campaigns that are scheduled can be updated. Only the name and SendAt fields can be changed. For non-scheduled campaigns, this endpoint will not update anything.

Request & Response Schemas

CreateCampaignRequest

type CreateCampaignRequest struct {
  Name      string
  Message   string
  Clients   []CampaignClient
  JSON      string
  TempMsgID string
  SendAt    string
}

DeleteCampaignRequest

type DeleteCampaignRequest struct {
  ID int
}

UpdateCampaignRequest

type UpdateCampaignRequest struct {
  ID     int
  Name   string
  SendAt string
}

ResendCampaignMessageRequest

type ResendCampaignMessageRequest struct {
  MessageKey string
}

CampaignResponse

type CampaignResponse struct {
  ID             int
  Name           string
  TemplateName   string
  Lang           string
  CreatedAt      string
  UpdatedAt      string
  SendAt         string
  Status         string
  AgentID        int
  Message        string
  JSON           string
  SentCount      int
  DeliveredCount int
  FailedCount    int
  Total          int
  Clients        []CampaignClient
  CompanyID      int
  ReportHeaders  interface{}
  TempMsgID      string
  Error          string
  SocketKey      string
}

CampaignClient

type CampaignClient struct {
  AccountID string
  Params    []string
}

Validation & Business Rules

Rule Description	Applies To	Error Message
At least 2 clients required	Create Campaign	"invalid request: at least 2 clients required"
TempMsgID must exist if provided	Create Campaign	"invalid request: template not found"
JSON or TempMsgID required	Create Campaign	"invalid request: JSON or TempMsgID required"
If TempMsgID is present and Message is empty, BODY text is auto-filled from template	Create Campaign	(auto-filled, no error)
Params count must match variables in JSON (first client)	Create Campaign	"invalid request: not enough params for variables in JSON"
Each client's params count must match number of variables in template	Create Campaign	"invalid request: each client must have params for all template variables"
Only scheduled campaigns can be updated (name and SendAt only)	Update Campaign	"only scheduled campaigns can be updated (name and SendAt fields only)"

All endpoints require X-API-Key header.

Error Handling

400 Bad Request: Invalid request body, missing required fields, or validation errors.
502 Bad Gateway: Upstream service call failed.
500 Internal Server Error: Server-side error or marshalling failure.

Examples

Create Campaign Request Examples

1. Only TempMsgID

{
  "name": "Order Confirmation Campaign",
  "clients": [
    {
      "accountID": "+966539078942",
      "params": ["John", "ORD-12345"]
    }
  ],
  "TempMsgID": "c8630dcb-dc36-4968-8ca4-26a78893c1e6",
  "SendAt": "2025-03-03T14:32:25+03:00"
}

Behavior: The template with this TempMsgID will be used. If the template has a BODY, its text will be auto-filled as the campaign message. JSON will be auto-filled from the template.

2. TempMsgID and JSON

{
  "name": "Order Confirmation Campaign",
  "clients": [
    {
      "accountID": "+966539078942",
      "params": ["John", "ORD-12345"]
    }
  ],
  "TempMsgID": "c8630dcb-dc36-4968-8ca4-26a78893c1e6",
  "JSON": "{ \"to\": \"<accountID>\", \"type\": \"template\", \"template\": { \"namespace\": \"<namespace>\", \"language\": { \"policy\": \"deterministic\", \"code\": \"en_US\" }, \"name\": \"order_confirmation\", \"components\": [] } }",
  "SendAt": "2025-03-03T14:32:25+03:00"
}

Behavior: The template with this TempMsgID will be used, but the provided JSON will override the template's JSON.

3. TempMsgID, JSON, and Message

{
  "name": "Order Confirmation Campaign",
  "clients": [
    {
      "accountID": "+966539078942",
      "params": ["John", "ORD-12345"]
    }
  ],
  "TempMsgID": "c8630dcb-dc36-4968-8ca4-26a78893c1e6",
  "JSON": "{ \"to\": \"<accountID>\", \"type\": \"template\", \"template\": { \"namespace\": \"<namespace>\", \"language\": { \"policy\": \"deterministic\", \"code\": \"en_US\" }, \"name\": \"order_confirmation\", \"components\": [] } }",
  "message": "Thank you for your order, John! Your order number is ORD-12345.",
  "SendAt": "2025-03-03T14:32:25+03:00"
}

Behavior: The template with this TempMsgID will be used, the provided JSON will override the template's JSON, and the provided message will override the template's BODY text.

4. All Fields (Typical Example)

{
  "name": "Welcome Back Campaign",
  "message": "We are happy to see you back again.",
  "clients": [
    {
      "accountID": "+966539078942",
      "params": ["https://example.com/image1.png", ""]
    }
  ],
  "JSON": "{ \"to\": \"<accountID>\", \"type\": \"template\", ... }",
  "TempMsgID": "c8630dcb-dc36-4968-8ca4-26a78893c1e6",
  "SendAt": "2025-03-03T14:32:25+03:00"
}

Behavior: All fields are explicitly set. The provided values will be used directly.

Note:
name is required and indicates the campaign name.
SendAt is optional and can be used to schedule the campaign (ISO 8601 format, e.g. "2025-03-03T14:32:25+03:00").

Delete Campaign Request

{
  "id": 385
}

Update Campaign Request

{
  "id": 387,
  "name": "test22",
  "SendAt": "2025-03-04T11:31:25.000Z"
}

Resend Campaign Message Request

{
  "messageKey": "C030200170205C476A3B882B2702FF"
}

Documentation