> ## Documentation Index
> Fetch the complete documentation index at: https://doc.convo.co.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Send a WhatsApp Message Using an Existing API Campaign

> Trigger a per-contact WhatsApp campaign send with dynamic template parameters, optional media, custom attributes, and contact tagging for enrichment.

Trigger a WhatsApp message to a single contact using a `LIVE` API campaign. You supply the contact's details, the campaign to use, and the dynamic values to fill into the template's placeholders — Convo handles routing the message through the WhatsApp Business API.

Each call sends to exactly one contact. To send to multiple contacts, call this endpoint once per recipient (in parallel or sequentially).

## Endpoint

```text theme={null}
POST https://connect.api-wa.co/project-apis/v1/project/{project_id}/campaign/api/send
```

## Authentication

```text theme={null}
X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD
```

## Path Parameters

<ParamField path="project_id" type="string" required>
  Your Convo project ID.
</ParamField>

## Request Body

<ParamField body="name" type="string" required>
  The contact's full name. Used to create or update the contact record in Convo.
</ParamField>

<ParamField body="phone_number" type="string" required>
  The contact's phone number including the country code, without a leading `+` or spaces (e.g., `"917089379345"` for an Indian number). If the country code is omitted, provide `default_country_code` to prepend it automatically.
</ParamField>

<ParamField body="campaign_name" type="string" required>
  The `name` of the API campaign to use for this send. The campaign must have `status: "LIVE"`. Use the name you specified when [creating the campaign](/api-reference/campaigns/create-campaign).
</ParamField>

<ParamField body="template_params" type="array">
  An ordered array of string values to substitute into the template's `{{1}}`, `{{2}}`, `{{3}}` placeholders. The number of items must exactly match `total_parameters` on the linked template.

  You can use the following dynamic variables anywhere in the array:

  | Variable     | Replaced with                                   |
  | ------------ | ----------------------------------------------- |
  | `$Name`      | The contact's full name (value of `name` field) |
  | `$FirstName` | The contact's first name (first word of `name`) |

  **Example:** `["Priya", "#ORD-789", "3"]`
</ParamField>

<ParamField body="media" type="object">
  Required for campaigns linked to `IMAGE`, `VIDEO`, or `FILE` type templates. Contains:

  | Field      | Type   | Description                                                                                         |
  | ---------- | ------ | --------------------------------------------------------------------------------------------------- |
  | `url`      | string | A publicly accessible URL for the media file. Must be reachable by WhatsApp's servers at send time. |
  | `filename` | string | The display filename (e.g., `"invoice_4521.pdf"`). Required for `FILE` type templates.              |
</ParamField>

<ParamField body="source" type="string">
  The acquisition source for this contact (e.g., `"website"`, `"facebook_ad"`, `"referral"`). Stored on the contact record for segmentation and analytics.
</ParamField>

<ParamField body="attributes" type="object">
  A key-value object of custom attributes to set on the contact record. Keys must correspond to existing custom attribute definitions in your Convo project.

  **Example:** `{"plan": "premium", "city": "Mumbai", "order_value": "1299"}`
</ParamField>

<ParamField body="default_country_code" type="string">
  A country code (without `+`) to prepend to `phone_number` if the number does not already include one. For example, `"91"` for India. Useful when your data source stores numbers without country codes.
</ParamField>

<ParamField body="tags" type="array">
  An array of tag name strings to assign to the contact. Tags must already exist in your Convo project — this endpoint does not create new tags.

  **Example:** `["vip", "Q4-cohort"]`
</ParamField>

## Request Examples

<Tabs>
  <Tab title="Simple Send">
    Send a shipping update with order details as template parameters:

    ```bash theme={null}
    curl -X POST "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/campaign/api/send" \
      -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Priya",
        "phone_number": "917089379345",
        "campaign_name": "ShipmentAlerts_Q4_2024",
        "template_params": ["#ORD-789", "3"]
      }'
    ```
  </Tab>

  <Tab title="Full Send with Media, Attributes & Tags">
    Send an invoice document with full contact enrichment:

    ```bash theme={null}
    curl -X POST "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/campaign/api/send" \
      -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Rahul Sharma",
        "phone_number": "917089379345",
        "campaign_name": "InvoiceDelivery_2024",
        "template_params": ["$FirstName", "#INV-1042", "₹4,599"],
        "media": {
          "url": "https://cdn.example.com/invoices/INV-1042.pdf",
          "filename": "Invoice_INV-1042.pdf"
        },
        "source": "shopify_checkout",
        "attributes": {
          "plan": "premium",
          "city": "Mumbai",
          "last_order_value": "4599"
        },
        "tags": ["premium-customer", "Q4-cohort"],
        "default_country_code": "91"
      }'
    ```
  </Tab>
</Tabs>

## Response

A successful send returns `200 OK`.

```json theme={null}
{
  "status": "success"
}
```

A `success` response means Convo has accepted and queued the message for delivery. It does not guarantee delivery to the end user's device — use webhook events or the [Get Campaign](/api-reference/campaigns/get-campaign) endpoint to track delivery status.

## Error Responses

| Status                      | Description                                                                                                                                                                                             |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`           | The contact phone number is invalid, `campaign_name` does not exist or is not `LIVE`, the number of `template_params` does not match the template's `total_parameters`, or a required field is missing. |
| `500 Internal Server Error` | An unexpected server-side error occurred.                                                                                                                                                               |

```json theme={null}
{
  "error": "Bad Request",
  "message": "template_params count (2) does not match template parameter count (3)."
}
```