RCS Campaign API

1. Overview

A working integration has three moving parts. A template defines what the message looks like and which variables it accepts. A campaign pairs that template with a contact list and submits it for delivery. A webhook receives the delivery and click events that follow. Build them in that order — a campaign cannot reference a template that does not yet exist.

BASE URL — https://app.fonada.ai/functions/v1

1.1 Conventions used in this document

2. Authentication

Every request carries an API key in the Authorization header as a bearer token. Keys are issued per workspace from the Fonada console and are prefixed with fsk_. Requests and responses are JSON, and Content-Type must be set on every call.

Authorization: Bearer fsk_your_api_key_here
Content-Type: application/json

3. Send a campaign message

POST /rcs_campaign_launcher

Pairs an existing template with a list of contacts and submits the campaign for delivery. Each contact may carry its own params object, which fills the {{variable}} placeholders defined in the template.

curl --location 'https://app.fonada.ai/functions/v1/rcs_campaign_launcher' \
--header 'Authorization: Bearer fsk_your_api_key_here' \
--header 'Content-Type: application/json' \
--data '{
  "template_name": "MY_Template2",
  "campaign_name": "March_Bulk_Promo",
  "contacts": [
    { "mobile": "98xxxxxxxx", "params": { "name": "John",  "city": "Mumbai" } },
    { "mobile": "76xxxxxxxx", "params": { "name": "Priya", "city": "Delhi"  } }
  ]
}'

3.1 Request body

3.2 Response

{
  "status": "success",
  "campaign_id": "camp-20260330-xyz",
  "messages_queued": 2
}

4. Template management

POST /rcs_template_manager

Templates are reusable message designs. Create one, then reference it by name from any campaign. All three types use this endpoint; the template_type field selects the layout.

4.1 Plain text template

A text message with optional quick-reply and URL suggestions.

curl --location 'https://app.fonada.ai/functions/v1/rcs_template_manager' \
--header 'Authorization: Bearer fsk_your_api_key_here' \
--header 'Content-Type: application/json' \
--data '{
  "action": "create_template",
  "template_name": "welcome_text_v1",
  "template_type": "text",
  "bot_name": "Fonada AI",
  "text": "Hello {{name}}, welcome to {{brand}}!",
  "suggestions": [
    { "type": "reply", "label": "Know More",     "postback": "know_more" },
    { "type": "url",   "label": "Visit Website", "url": "https://fonada.com" }
  ]
}'

4.2 Standalone rich card

A single card with a title, description, hero media, and action buttons.

curl --location 'https://app.fonada.ai/functions/v1/rcs_template_manager' \
--header 'Authorization: Bearer fsk_your_api_key_here' \
--header 'Content-Type: application/json' \
--data '{
  "action": "create_template",
  "template_name": "diwali_offer_v1",
  "template_type": "standalone",
  "bot_name": "Fonada AI",
  "title": "Special Offer for {{name}}",
  "description": "Get 20% off today!",
  "media_url": "https://cdn.example.com/offer-hero.jpg",
  "orientation": "VERTICAL",
  "media_height": "MEDIUM_HEIGHT",
  "suggestions": [
    { "type": "url",   "label": "Claim Offer", "url": "https://www.fonada.com/" },
    { "type": "phone", "label": "Call Us",     "phone": "+919876543210" }
  ]
}'

4.3 Carousel

A horizontally scrollable set of rich cards, used when one message needs to present several products or offers.

curl --location 'https://app.fonada.ai/functions/v1/rcs_template_manager' \
--header 'Authorization: Bearer fsk_your_api_key_here' \
--header 'Content-Type: application/json' \
--data '{
  "action": "create_template",
  "template_name": "Cars_Carousel",
  "template_type": "carousel",
  "bot_name": "Fonada AI",
  "card_width": "MEDIUM",
  "cards": [
    {
      "title": "Car A",
      "description": "Best sedan",
      "media_url": "https://example.com/a.jpg",
      "suggestions": [{ "type": "url", "label": "View", "url": "https://car-a.com" }]
    },
    {
      "title": "Car B",
      "description": "Best SUV",
      "media_url": "https://example.com/b.jpg",
      "suggestions": [{ "type": "url", "label": "View", "url": "https://car-b.com" }]
    }
  ]
}'

4.4 Suggestion types

5. Webhooks

Fonada posts a JSON payload to your configured webhook URL whenever a message changes state or a recipient taps a button. Acknowledge with 200 OK as soon as the payload is received and process it asynchronously; long-running work inside the request handler risks timeouts.

5.1 Delivery status events

{
  "event_type": "delivery_status",
  "timestamp": "2026-02-11T20:05:00Z",
  "message_id": "msg-123",
  "bot_id": "fonada-bot-12345",
  "recipient": "910000000000",
  "status": "delivered",
  "status_details": {
    "sent_at": "2026-02-11T20:00:00Z",
    "delivered_at": "2026-02-11T20:00:02Z"
  }
}

5.2 Status values

The statuses are independent of one another. A message may be delivered and never read, so treat delivery rate as a health metric and read rate as an engagement metric.

5.3 Failure payload

{
  "event_type": "delivery_status",
  "message_id": "msg-124",
  "status": "failed",
  "error": {
    "code": "INVALID_NUMBER",
    "message": "Phone number is invalid or not reachable"
  }
}

5.4 Button click events

When a recipient taps a suggestion, a button_click event is posted to the same webhook URL. Key your application logic on postback_data rather than button_text — the postback stays stable when the visible label changes.

{
  "event_type": "button_click",
  "timestamp": "2026-02-11T20:10:00Z",
  "message_id": "msg-123",
  "bot_id": "fonada-bot-12345",
  "user_phone": "910000000000",
  "interaction": {
    "type": "action",
    "button_text": "Buy Now",
    "postback_data": "buy_product_123",
    "url": "https://shop.com/buy?product=123"
  }
}

6. Response codes and errors

API responses

Webhook error codes

7. Operational guidance

1. Validate before you send. Confirm every contact supplies each variable the template declares, and normalise numbers to a consistent format.
2. Test on a small list first. Run one campaign per template type against a handful of internal numbers before a production send.
3. Make webhook handlers idempotent. Key on message_id plus status so a repeated event does not double-count a delivery.
4. Reconcile regularly. Compare submitted counts against your own records; discrepancies usually indicate duplicates or malformed rows in the audience list.
5. Use stable postback codes. Short machine-readable values such as BOOK_DEMO survive copy changes and keep downstream analytics consistent.

8. Support

For integration support, quote the campaign_id and the affected message_id when raising a ticket — these identify the exact send in platform logs.

Appendix A — Revision history