# SendRCS API Instructions for Claude

Copy this into your Claude Project's custom instructions or system prompt. If you use the SendRCS MCP server instead, you do not need any of this: connect `https://api.sendrcs.eu/api/mcp` as a Streamable HTTP server and the tools describe themselves.

---

## SendRCS API

You have access to the SendRCS API for sending interactive mobile messages via RCS (Rich Communication Services), with automatic SMS fallback for phones without RCS. Follow the reference below exactly: field names are case-sensitive and the validator rejects unknown fields.

<!-- Everything below is generated from https://docs.sendrcs.eu/openapi.yaml by scripts/build-ai-instructions.py. Edit the spec, not this file. -->

### Base URLs

- **RCS/SMS endpoints:** `https://api.sendrcs.eu/api/rcs`
- **Message Log:** `https://api.sendrcs.eu/api/messages`
- **Contacts API:** `https://api.sendrcs.eu/api/v1/contacts`
- **Groups API:** `https://api.sendrcs.eu/api/v1/groups`
- **Templates API:** `https://api.sendrcs.eu/api/v1/templates`

### Authentication

Every request needs the `X-API-Key` header, except the public sandbox endpoints below:

```
X-API-Key: <api_key>
```

API key for programmatic access. Obtain your API key by logging into your SendRCS account and navigating to Settings > Api Keys. A key can be restricted to specific public IP addresses or CIDR ranges in its settings; other addresses receive 403 (code IP_NOT_ALLOWED).

### Try it without an account (Sandbox)

You can validate and preview any message body before you have an API key. The sandbox runs the
same validator as `POST /send`, returns the same error shape, and gives you a phone-mockup preview
link. Nothing is sent, no credits are used, and no auth header is needed.

- `POST /sandbox/validate` - validation only
- `POST /sandbox/preview` - validation plus a `share_url` (expires after 24 hours)
- `GET /sandbox/samples` - sample images, a video and a PDF you may reference

Send the exact body you would send to `/send` or `/send-batch`. Recipient and sender fields
(`phoneNumber`, `sendernameId`, `scheduleAt`, ...) are accepted and listed under
`sandbox.ignored_fields`. Only media from `/sandbox/samples` is rendered; other `https` URLs still
pass validation but show as a placeholder in the preview. Rate limit: 20 requests per minute and
100 per day per IP. Sandbox preview ids cannot be used to send.

```bash
curl -X POST https://api.sendrcs.eu/api/rcs/sandbox/preview \
  -H "Content-Type: application/json" \
  -d '{
  "messageType": "richCard",
  "content": {
    "title": "Your order is on its way",
    "description": "Track the parcel or talk to us.",
    "media": {
      "height": "TALL",
      "contentInfo": {
        "fileUrl": "https://sendrcs.eu/images/rcsexamples/shoes-1.jpg",
        "contentType": "image/jpeg"
      }
    },
    "cardActions": [
      {
        "type": "openUrl",
        "text": "Track order",
        "openUrlAction": {
          "url": "https://example.com/track"
        }
      },
      {
        "type": "dial",
        "text": "Call us",
        "dialAction": {
          "phoneNumber": "+4512345678"
        }
      }
    ]
  }
}'
```

Read `valid`, `errors`, `warnings`, `preview.share_url` and `preview.expires_at`. Show the developer the `share_url`: it renders the message on a phone mockup (Android and iOS). When they are ready, they create a free account at https://app.sendrcs.eu/auth/signup and you call `/send` with their API key.

### Message types

`messageType` is one of: `text`, `textBasic`, `richCard`, `carousel`, `media`, `file`, `image`, `video`, `audio`.

- **text** - `text` string + optional `suggestions` (max 11 chips)
- **textBasic** - `text` string only (no suggestions, max 160 characters)
- **richCard** - At least `title` or `description` required, optional `media` (omitted if no fileUrl), `cardActions` (max 4), optional `suggestions` (max 11)
- **carousel** - `cardContents` array (max 10 cards, each requiring at least `title` or `description`, optional `media`) + optional `suggestions`
- **media** - `url` + optional `caption` (sent as rich card if caption present), or `media` object + optional `suggestions`
- **file** - `url` or `media` object with file URL (PDFs, documents, etc.)
- **image** - `url` or `media` object with image URL + optional `caption`
- **video** - `url` or `media` object with video URL + optional `caption`
- **audio** - `url` or `media` object with audio URL

### Send a single message - `POST https://api.sendrcs.eu/api/rcs/send`

Send an RCS message to a single recipient. Supports all message types (text, richCard, carousel, media) with optional SMS fallback and scheduling.

Text with reply chips:

```bash
curl -X POST https://api.sendrcs.eu/api/rcs/send \
  -H "X-API-Key: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+4512345678",
  "messageType": "text",
  "sendernameId": "60f1b2c3d4e5f6a7b8c9d0e1",
  "content": {
    "text": "Hello! How can we help you today?",
    "suggestions": [
      {
        "reply": {
          "text": "Book Appointment",
          "postbackData": "book_appointment",
          "webhookUrl": "https://yourapp.com/webhooks/rcs"
        }
      },
      {
        "reply": {
          "text": "Get Support",
          "postbackData": "get_support",
          "webhookUrl": "https://yourapp.com/webhooks/rcs"
        }
      },
      {
        "action": {
          "text": "Call Us",
          "type": "dial",
          "dialAction": {
            "phoneNumber": "+4512345678"
          }
        }
      }
    ]
  }
}'
```

Rich card with image and buttons:

```bash
curl -X POST https://api.sendrcs.eu/api/rcs/send \
  -H "X-API-Key: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+4512345678",
  "messageType": "richCard",
  "sendernameId": "60f1b2c3d4e5f6a7b8c9d0e1",
  "content": {
    "title": "Special Offer - 50% Off!",
    "description": "Limited time offer on premium products.",
    "cardOrientation": "VERTICAL",
    "media": {
      "height": "MEDIUM",
      "contentDescription": "Laptop and headphones on a desk, product photo",
      "contentInfo": {
        "fileUrl": "https://sendrcs.eu/images/rcsexamples/tech.jpg"
      },
      "thumbnailUrl": "https://sendrcs.eu/images/rcsexamples/tech.jpg"
    },
    "cardActions": [
      {
        "text": "Shop Now",
        "type": "openUrl",
        "openUrlAction": {
          "url": "https://shop.example.com"
        }
      },
      {
        "text": "Get Details",
        "type": "postback",
        "postbackData": "offer_details",
        "webhookUrl": "https://yourapp.com/webhooks/rcs"
      }
    ]
  },
  "smsFallback": {
    "message": "50% Off! Shop: shop.example.com",
    "sendernameId": "60f1b2c3d4e5f6a7b8c9d0e2"
  }
}'
```

Carousel:

```bash
curl -X POST https://api.sendrcs.eu/api/rcs/send \
  -H "X-API-Key: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+4512345678",
  "messageType": "carousel",
  "sendernameId": "60f1b2c3d4e5f6a7b8c9d0e1",
  "content": {
    "cardContents": [
      {
        "title": "Product 1",
        "description": "Description of product 1",
        "media": {
          "height": "MEDIUM",
          "contentDescription": "Product 1 photographed on a white background",
          "contentInfo": {
            "fileUrl": "https://sendrcs.eu/images/rcsexamples/tech-1.jpg"
          }
        },
        "cardActions": [
          {
            "text": "Buy Now",
            "type": "openUrl",
            "openUrlAction": {
              "url": "https://shop.example.com/product1"
            }
          }
        ]
      },
      {
        "title": "Product 2",
        "description": "Description of product 2",
        "media": {
          "height": "MEDIUM",
          "contentInfo": {
            "fileUrl": "https://sendrcs.eu/images/rcsexamples/tech-2.jpg"
          }
        },
        "cardActions": [
          {
            "text": "Buy Now",
            "type": "openUrl",
            "openUrlAction": {
              "url": "https://shop.example.com/product2"
            }
          }
        ]
      }
    ],
    "suggestions": [
      {
        "reply": {
          "text": "View All",
          "postbackData": "view_all",
          "webhookUrl": "https://yourapp.com/webhooks/rcs"
        }
      }
    ]
  }
}'
```

### Options on `/send` and `/send-batch`

- `sendernameId` - ID of an approved RCS sender (see `/senders`)
- `contactId` - Optional existing contact ID
- `skipContactCreation` - Skip creating a contact record (not allowed for conversation-based senders)
- `skipDisabled` - Skip sending to disabled contacts
- `campaignName` - Campaign name for tracking
- `scheduleAt` - ISO 8601 date-time for scheduling
- `timeZone` - IANA timezone for scheduling
- `smsFallback` - SMS fallback when RCS is unavailable

### Send to many recipients - `POST https://api.sendrcs.eu/api/rcs/send-batch` (up to 10,000)

Send the same RCS message to multiple recipients (up to 10,000).

```bash
curl -X POST https://api.sendrcs.eu/api/rcs/send-batch \
  -H "X-API-Key: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumbers": [
    "+4512345678",
    "+4587654321",
    "+4511223344"
  ],
  "messageType": "text",
  "sendernameId": "60f1b2c3d4e5f6a7b8c9d0e1",
  "content": {
    "text": "Hello! This is a batch message."
  },
  "campaignName": "February Campaign"
}'
```

The response is `202` with a job id; poll `GET /batch/{jobId}/status` or cancel the whole batch with `DELETE /batch/{jobId}`.

### Scheduling

Messages can be scheduled for future delivery using `scheduleAt` (ISO 8601 datetime) and `timeZone` (IANA format, e.g., `Europe/Copenhagen`). If no timezone is given, your account's default timezone applies.

```bash
curl -X POST https://api.sendrcs.eu/api/rcs/send \
  -H "X-API-Key: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+4512345678",
  "messageType": "text",
  "sendernameId": "60f1b2c3d4e5f6a7b8c9d0e1",
  "content": {
    "text": "Your appointment reminder for tomorrow at 10:00 AM"
  },
  "scheduleAt": "2024-02-15T09:00:00",
  "timeZone": "Europe/Copenhagen"
}'
```

**Cancel a scheduled message:** `DELETE https://api.sendrcs.eu/api/messages/{id}` (note the base path `https://api.sendrcs.eu/api`, not `https://api.sendrcs.eu/api/rcs`).

Cancel one scheduled message before it is sent, by its message ID.
Works the same way for RCS and SMS - a scheduled `/send` and a scheduled
`/send-sms` both produce one cancellable message record.

Only messages still in `SCHEDULED` status can be cancelled. Anything already
sending or sent returns `404` - once a message has left, it cannot be called back.
The scheduled job is cancelled and the message record is removed, so the message
no longer appears in the message log.

**Cancelling one recipient of a scheduled batch** works too: pass that recipient's
message ID and only their message is dropped. The rest of the batch is untouched
and still goes out on schedule. To cancel the whole batch instead, use
`DELETE /batch/{jobId}` - do not loop this endpoint
over every recipient.

**Finding the ID:** a scheduled send (`/send` or `/send-sms` with `scheduleAt`)
returns `{ "scheduled": true, "jobId": "...", "messageId": "..." }` - `messageId`
is the ID to pass here. Note that scheduled responses do not carry
`messageRecordId`; that field appears only on immediate sends. You can also list
everything still pending with
`GET /messages/log?status=SCHEDULED` and use the `id`
of a row.

Requires the `messages:write` permission.

### SMS fallback

Any RCS message can include `smsFallback` for devices without RCS support:

- `smsFallback.message` - SMS fallback text. Supports the same merge fields as the RCS body (contact, company and custom fields, `{{today}}`, `{{unsubscribe_link}}`), substituted per recipient when the fallback is sent. `{{unsubscribe_link}}` becomes a unique per-recipient opt-out URL when the recipient is a contact.
- `smsFallback.sendernameId` - SMS sender ID

```bash
curl -X POST https://api.sendrcs.eu/api/rcs/send-batch \
  -H "X-API-Key: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumbers": [
    "+4512345678",
    "+4587654321"
  ],
  "messageType": "richCard",
  "sendernameId": "60f1b2c3d4e5f6a7b8c9d0e1",
  "content": {
    "title": "Special Offer",
    "description": "Limited time discount",
    "media": {
      "height": "MEDIUM",
      "contentInfo": {
        "fileUrl": "https://sendrcs.eu/images/rcsexamples/tech-3.jpg"
      }
    },
    "cardActions": [
      {
        "text": "Shop Now",
        "type": "openUrl",
        "openUrlAction": {
          "url": "https://shop.example.com"
        }
      }
    ]
  },
  "smsFallback": {
    "message": "Special offer! Visit shop.example.com",
    "sendernameId": "60f1b2c3d4e5f6a7b8c9d0e2"
  },
  "skipDisabled": true,
  "batchSize": 100,
  "delayMs": 50
}'
```

### Files, images, video, audio

Use `messageType` `file`, `image`, `video` or `audio` with a public `https` URL. An image with a `caption` is delivered as a rich card.

- `media.height` - Media height
- `media.contentDescription` - Alt text for the image or video, read aloud by screen readers. Plain text, max 200 characters. Describe what the picture shows in a factual way, without URLs or promotional copy. Optional.
- `media.thumbnailUrl` - Placeholder image URL shown while media loads

```bash
curl -X POST https://api.sendrcs.eu/api/rcs/send \
  -H "X-API-Key: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+4512345678",
  "messageType": "file",
  "sendernameId": "60f1b2c3d4e5f6a7b8c9d0e1",
  "content": {
    "media": {
      "contentInfo": {
        "fileUrl": "https://example.com/document.pdf"
      }
    }
  }
}'
```

### Standalone SMS - `POST https://api.sendrcs.eu/api/rcs/send-sms`

Send an SMS message to a single recipient, independently of RCS.
Specify your SMS sender ID and message content. Billed at standard SMS rate per message segment.

**Features:**
- Standalone SMS — no RCS sending or fallback involved
- Full merge field support: `{{contact_first_name}}`, `{{company_name}}`, custom field tags, `{{today}}`, and `{{unsubscribe_link}}` - replaced per recipient before segments are calculated
- Tracked store links: when a Shopify store is connected, links to that store are replaced by short tracked links at send time, so clicks and purchases show up in statistics. The billed segment count reflects the final text. Requires a contact (not with `skipContactCreation`); can be turned off on the Shopify settings page.
- Timezone-aware scheduling
- `skipContactCreation`: Send without creating a contact record
- `skipDisabled`: Skip sending to disabled contacts (default: true)

```bash
curl -X POST https://api.sendrcs.eu/api/rcs/send-sms \
  -H "X-API-Key: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+4512345678",
  "message": "Hi {{contact_first_name}}! Your order from {{company_name}} is ready for pickup.",
  "sendernameId": "60f1b2c3d4e5f6a7b8c9d0e2",
  "campaignName": "Order Ready"
}'
```

### Limits

**RCS Limits**

| Limit | Value |
|-------|-------|
| Text | max 3072 characters |
| Rich card title | max 200 characters |
| Rich card description | max 2000 characters |
| Card actions (buttons ON the card) | max 4, max 25 characters each |
| Suggestion chips (below the card) | max 11, max 25 characters each |
| Carousel | max 10 cards |
| Batch | max 10,000 recipients |
| Media | max 100 MB |
| Email and web addresses in a text message | an email address, URL, www. host or bare domain (such as example.com) in the `text` of a text or textBasic message returns a validation WARNING (the message is still accepted): iPhones reject such messages, Android delivers them. To reach every phone put links on chips or buttons, or use a rich card; card titles, descriptions and chip labels may contain an address |
| Campaign name | max 100 characters |

**SMS Limits**

| Limit | Value |
|-------|-------|
| SMS message | max 1530 characters |
| Single segment (GSM-7) | 160 characters |
| Single segment (Unicode) | 70 characters |
| Multi-part segment (GSM-7) | 153 characters per segment |
| Multi-part segment (Unicode) | 67 characters per segment |

### Buttons and chips

`cardActions` are the buttons on a rich card or carousel card; `suggestions` are the chips under any message. A chip is either `{ "reply": {...} }` (text reply that posts `postbackData` to your webhook) or `{ "action": {...} }` (same shape as a card button).

Chip suggestion (reply button or action). Action chips use the CardAction shape, so an openUrlInWebview chip supports openUrlInWebviewAction.viewMode (FULL, TALL, or HALF) exactly like an openUrlInWebview card action - viewMode is not card-only. Exceptions: postback and addToCalendar are card-only (use a reply chip with postbackData, and createCalendarEvent with createCalendarEventAction, respectively); the unsubscribe stop-keyword type is chip-only.

Action types: `postback`, `openUrl`, `openUrlInWebview`, `dial`, `addToCalendar`, `createCalendarEvent`, `viewLocation`, `shareLocation`, `unsubscribeLink`, `unsubscribe`. postback and addToCalendar are valid on card buttons only; createCalendarEvent and unsubscribe are valid on chips only. All other types are valid on both.

- `postbackData` - Data sent to webhook on click
- `webhookUrl` - Webhook URL for postback actions
- `openUrlInWebviewAction` - Opens URL in the messaging app's webview (not the external browser), so the recipient stays in the conversation. Pair with type "openUrlInWebview" on both card buttons and chips. Example: {"type":"openUrlInWebview","text":"Shop now","openUrlInWebviewAction":{"url":"https://shop.example.com","viewMode":"FULL"}}
- `calendarAction` - Calendar action for card buttons (type: addToCalendar). Card-only - chips use createCalendarEventAction with type createCalendarEvent instead.
- `createCalendarEventAction` - Calendar action for chips (type: createCalendarEvent). Chip-only - card buttons use calendarAction with type addToCalendar instead.
- `shareLocationAction` - Prompts user to share their current location (no properties required)
- `unsubscribeAction` - Unsubscribe action — sends a stop keyword as a reply to trigger the unsubscribe flow. Chip-only (not available as a card action). The stopKeyword is auto-corrected at preview time to match the active trigger configuration for the sendername.

Open a page inside the messaging app (webview):

```bash
curl -X POST https://api.sendrcs.eu/api/rcs/send \
  -H "X-API-Key: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+4512345678",
  "messageType": "richCard",
  "sendernameId": "60f1b2c3d4e5f6a7b8c9d0e1",
  "content": {
    "title": "New arrivals",
    "description": "Browse the collection without leaving the chat.",
    "cardOrientation": "VERTICAL",
    "media": {
      "height": "TALL",
      "contentInfo": {
        "fileUrl": "https://sendrcs.eu/images/rcsexamples/shoes-1.jpg"
      }
    },
    "cardActions": [
      {
        "text": "Shop now",
        "type": "openUrlInWebview",
        "openUrlInWebviewAction": {
          "url": "https://shop.example.com/new?utm_source=rcs",
          "viewMode": "FULL"
        },
        "postbackData": "shop_now",
        "webhookUrl": "https://yourapp.com/webhooks/rcs"
      }
    ],
    "suggestions": [
      {
        "action": {
          "text": "Size guide",
          "type": "openUrlInWebview",
          "openUrlInWebviewAction": {
            "url": "https://shop.example.com/size-guide",
            "viewMode": "FULL"
          }
        }
      },
      {
        "action": {
          "text": "Unsubscribe",
          "type": "unsubscribeLink",
          "openUrlAction": {
            "url": "{{unsubscribe_link}}"
          }
        }
      }
    ]
  }
}'
```

Marketing message with the required unsubscribe button:

```bash
curl -X POST https://api.sendrcs.eu/api/rcs/send \
  -H "X-API-Key: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+4512345678",
  "messageType": "richCard",
  "sendernameId": "60f1b2c3d4e5f6a7b8c9d0e1",
  "content": {
    "title": "Special Offer - 50% Off!",
    "description": "Limited time offer on premium products.",
    "cardOrientation": "VERTICAL",
    "media": {
      "height": "MEDIUM",
      "contentInfo": {
        "fileUrl": "https://sendrcs.eu/images/rcsexamples/tech.jpg"
      },
      "thumbnailUrl": "https://sendrcs.eu/images/rcsexamples/tech.jpg"
    },
    "cardActions": [
      {
        "text": "Shop Now",
        "type": "openUrl",
        "openUrlAction": {
          "url": "https://shop.example.com"
        }
      },
      {
        "text": "Unsubscribe",
        "type": "unsubscribeLink",
        "openUrlAction": {
          "url": "{{unsubscribe_link}}"
        }
      }
    ]
  }
}'
```

### Merge fields and the unsubscribe link

Message text supports `{{merge_field}}` placeholders, replaced per recipient at send time.

- **RCS** (`/send`, `/send-batch`): full set — contact fields (`{{contact_first_name}}`,
  `{{contact_last_name}}`, `{{contact_phone}}`, `{{contact_email}}`), company fields
  (`{{company_name}}`, `{{company_phone}}`, `{{company_website}}`, …), `{{today}}`,
  custom field tags (`{{your_tag}}`), and `{{unsubscribe_link}}`. Placeholders work in text,
  card titles/descriptions, and button/chip URLs.
- **Standalone SMS** (`/send-sms`): full set - same contact/company/custom fields, `{{today}}`,
  and `{{unsubscribe_link}}` as RCS. Contact and custom fields require the recipient to be an
  existing contact (or one is auto-created unless `skipContactCreation: true`); unknown
  placeholders are replaced with an empty string.
- **SMS fallback text** (`smsFallback.message` on RCS sends): same set as the RCS body -
  contact, company and custom fields, `{{today}}` and `{{unsubscribe_link}}`. Substituted
  per recipient at the moment the fallback is sent, whichever reason triggered it. Contact,
  custom and unsubscribe fields need a real contact; without one they resolve to an empty
  string (unsubscribe placeholder stays as written) while company fields still work.

**`{{unsubscribe_link}}`** is replaced with a unique, per-recipient opt-out URL
(`https://stoprcs.eu/u/<token>`, or your configured custom unsubscribe URL). A fresh token is
issued on every send. Because the link is bound to a specific contact, it resolves only when the
message is sent to a contact — it is **not** replaced when `skipContactCreation: true` is used for
a phone number that is not already a contact (the placeholder is left as-is). Recommended on
marketing/promotional messages to provide a compliant opt-out.

### Conversation billing

Some senders use conversation-based billing. A conversation starts when one party responds to the other within 24 hours: your first reply to a message the recipient sent you, or the recipient's reply to a message you sent. The 24-hour window runs from that response and all messages inside it are free. A message from the recipient alone never opens a window. Use `rcs_conversation_status` to check if a phone number has an open window before sending follow-ups.

### Message log and interactions

**Message history** - `GET https://api.sendrcs.eu/api/messages/log`

Retrieve your message history with filtering and cursor-based pagination. Supports filtering by phone number, campaign name, direction, status, and message type. **Single message lookup:** Pass `messageId` to retrieve a specific message by ID (no date range needed). **Date range:** Defaults to last 7 days if not provided. Maximum range is 31 days per request. **Pagination:** Uses cursor-based pagination. Follow the `nextCursor` value from each response to fetch the next page. When `hasNext` is `false`, you've reached the end. **Base URL:** `https://api.sendrcs.eu/api/messages/log` **Example request:** ``` GET https://api.sendrcs.eu/api/messages/log?startDate=2026-05-01T00:00:00Z&endDate=2026-05-07T23:59:59Z&status=DELIVERED,READ&limit=200 ```

**Button clicks and typed replies** - `GET https://api.sendrcs.eu/api/messages/interactions`

Every button tap and every typed reply on the messages you sent, newest first. Each row carries `messageId`: the sent message the button belonged to. Join it with `GET /messages/log?messageId=` for the delivery details or `GET /messages/{id}/content` for the exact rich card or chips that were tapped. **Interaction types:** `button_click` (a reply chip or an action button was tapped; `buttonType` tells `reply` from `action` and `actionType` names the action) and `reply_received` (the contact typed a message instead of tapping). **One message:** pass `messageId` to get the clicks on that message only (no date range needed). **Date range:** defaults to the last 7 days. Maximum range is 31 days per request. **Pagination:** cursor-based, like the message log. Follow `pagination.nextCursor` until `hasNext` is `false`. **Tracked store links** log two rows per tap, a postback and the redirect; …

### Webhooks

Button click, incoming RCS message, incoming SMS message, delivery status, and form submission callbacks. Configure your webhook URLs in Settings > Webhooks (https://app.sendrcs.eu/settings/webhooks) after logging in.

- `buttonClick` - Button click callback
- `deliveryStatus` - Delivery status callback
- `rcsIncoming` - Incoming RCS message callback
- `smsIncoming` - Incoming SMS message callback
- `formSubmission` - Form submission callback
- `formOptInConfirmed` - Form opt-in confirmed callback

Every outbound webhook request includes an `X-RCS-Signature` header so you can verify it genuinely came from SendRCS and hasn't been tampered with. **Signature verification is optional** — if you don't need it, you can safely ignore the header and process the JSON body directly. It's recommended for production integrations handling sensitive actions. **Header format (Stripe-style):**

### Responses and errors

`POST /send` returns `SendMessageResponse`:

- `success` (boolean) - `true` when the message was handed to the network (RCS) or queued for sending (SMS fallback). This is an acceptance result, not a delivery result: use status webhooks or `GET /api/messages/log` for the final delivery status.
- `messageId` (string) - Network message ID for RCS sends. Null when the SMS fallback was used (the SMS is queued).
- `messageRecordId` (string) - Internal message record ID. Use this to correlate with status webhook and button click webhook events and to look the message up in `GET /api/messages/log?messageId=`. When the SMS fallback was used this is the ID of the RCS record the fallback belongs to.
- `method` (string, one of `RCS`, `SMS_FALLBACK`) - Channel actually used. `SMS_FALLBACK` when the SMS fallback was queued instead of RCS.
- `scheduled` (boolean)
- `queued` (boolean) - `true` when the message (SMS fallback) is queued and will be sent asynchronously.
- `creditsUsed` (number) - Credits charged for an RCS send. For a queued SMS fallback this equals `estimatedCredits`; the actual charge happens when the SMS is sent.
- `estimatedCredits` (number) - Credits charged (RCS) or expected to be charged (queued SMS fallback). `0` when nothing will be charged.
- `fallbackUsed` (boolean) - `true` when the SMS fallback was sent instead of RCS.
- `fallbackWillBeUsed` (boolean)
- `fallbackReason` (string) - Why the fallback (or no fallback) was used, e.g. `COUNTRY_NOT_SUPPORTED`, `COUNTRY_BLOCKED`, `PROVIDER_ERROR`, `NO_FALLBACK_COUNTRY_NOT_SUPPORTED`, `NO_FALLBACK_COUNTRY_BLOCKED`, `NO_FALLBACK_PROVIDER_ERROR`, or `SMS_COUNTRY_NOT_SUPPORTED` when neither RCS nor SMS is available for the destination (then `success` is `false` and nothing is sent or charged).
- `hasInteractiveButtons` (boolean)
- `error` (string) - Error details when `success` is `false`.
- `errorType` (string) - Error category when `success` is `false` (e.g. `INVALID_PHONE_NUMBER`, `VALIDATION_ERROR`).
- `countrySupported` (boolean) - `false` when RCS is not available for the destination country (not in the price list, or disabled in your account's country settings). The message is then either sent as SMS fallback (`fallbackUsed: true`) or fails (`success: false`).
- `countryError` (string) - Explanation when `countrySupported` is `false`. When SMS is not available for the destination either, the request fails synchronously (`success: false`, `fallbackReason: SMS_COUNTRY_NOT_SUPPORTED`) and this explains both.
- `conversation` (ConversationInfo)

Errors use `ErrorResponse` with HTTP `400` (validation, see `errors`), `401` (missing or invalid key), `403` (key not allowed from this IP, code `IP_NOT_ALLOWED`) or `404`:

- `message` (string)
- `error` (string)
- `errors` (array of object)
  - `msg` (string)
  - `param` (string)
  - `location` (string)

Always check `success`; a `false` comes with `message` and, for validation, an `errors` array.

Full reference: https://docs.sendrcs.eu/llms-full.txt (everything in one file) and https://docs.sendrcs.eu/openapi.yaml.
