# SendRCS API

> SendRCS API for sending rich, interactive messages via RCS (Rich Communication Services) with SMS fallback.

## Quick Start

Base URL: `https://api.sendrcs.eu/api/rcs`

Authentication: Bearer token or API key in `X-API-Key` header.

## Core Endpoints

### Send Single Message
POST /api/rcs/send

Send an RCS message to one recipient. Supports text, rich cards, carousels, and media with interactive buttons.

### Send Batch Messages
POST /api/rcs/send-batch

Send to up to 10,000 recipients. Automatic disabled contact filtering and progress tracking.

## Message Types

- **text**: Text with up to 11 chip suggestions (reply buttons)
- **textBasic**: Plain text only (no interactive elements)
- **richCard**: Card with image, title, description, and up to 4 action buttons + 4 chip suggestions
- **carousel**: Up to 10 rich cards in horizontal scroll
- **media**: Standalone image or video with optional suggestions
- **file**: Send files (PDF, documents, etc.)
- **image**: Send images (JPG, PNG, GIF, etc.)
- **video**: Send videos (MP4, etc.)
- **audio**: Send audio files (MP3, etc.)

## Key Features

- **Interactive Buttons**: Chip suggestions (11 max) and card actions (3 max per card)
- **SMS Fallback**: Automatic fallback when RCS unavailable
- **Scheduling**: Timezone-aware scheduling with `scheduleAt` and `timeZone`
- **skipContactCreation**: Send without creating contact records
- **Conversation Billing**: 24-hour conversation windows for cost optimization

## Example: Send Text with Buttons

```json
POST /api/rcs/send
{
  "phoneNumber": "+4512345678",
  "messageType": "text",
  "sendernameId": "60f1b2c3d4e5f6a7b8c9d0e1",
  "content": {
    "text": "Hello! How can we help?",
    "suggestions": [
      {
        "reply": {
          "text": "Book Appointment",
          "postbackData": "book",
          "webhookUrl": "https://yourapp.com/webhook"
        }
      },
      {
        "action": {
          "text": "Call Us",
          "type": "dial",
          "dialAction": { "phoneNumber": "+4512345678" }
        }
      }
    ]
  }
}
```

## Example: Rich Card with Actions

```json
{
  "phoneNumber": "+4512345678",
  "messageType": "richCard",
  "sendernameId": "60f1b2c3d4e5f6a7b8c9d0e1",
  "content": {
    "title": "Special Offer",
    "description": "50% off today!",
    "media": {
      "height": "MEDIUM",
      "contentInfo": { "fileUrl": "https://example.com/offer.jpg" }
    },
    "cardActions": [
      { "text": "Shop Now", "type": "openUrl", "openUrlAction": { "url": "https://shop.example.com" } },
      { "text": "Details", "type": "postback", "postbackData": "details", "webhookUrl": "https://yourapp.com/webhook" }
    ]
  },
  "smsFallback": {
    "message": "50% off! Visit shop.example.com",
    "sendernameId": "60f1b2c3d4e5f6a7b8c9d0e2"
  }
}
```

## Example: Send File/Image/Video/Audio

```json
{
  "phoneNumber": "+4512345678",
  "messageType": "file",
  "sendernameId": "60f1b2c3d4e5f6a7b8c9d0e1",
  "content": {
    "media": {
      "contentInfo": { "fileUrl": "https://example.com/document.pdf" }
    }
  }
}
```

Use `messageType`: `file`, `image`, `video`, or `audio` depending on the content type.

## Limits

- Max chip suggestions (text): 11
- Max chip suggestions (rich card): 4
- Max card actions: 4 per card
- Max carousel cards: 10
- Max batch recipients: 10,000
- Max text length: 2,000 characters
- Max button text: 25 characters
- Max SMS fallback: 1,530 characters

## Action Types for Chips

- `reply` - Postback to webhook
- `dial` - Open phone dialer
- `openUrl` - Open URL
- `createCalendarEvent` - Add to calendar
- `viewLocation` - Open maps
- `shareLocation` - Share location

## Webhooks

Your webhook URL receives button clicks:

```json
{
  "event": "button_interaction",
  "interaction": {
    "type": "button_click",
    "buttonText": "Book Appointment",
    "postbackData": "book_appointment"
  },
  "contact": {
    "phone": "+4512345678",
    "name": "John Doe"
  }
}
```

## Full Documentation

- OpenAPI Spec: /openapi.yaml
- AI Instructions: /ai-instructions/

## Optional

- /ai-instructions/claude.md - Claude/Anthropic instructions
- /ai-instructions/chatgpt.md - ChatGPT instructions
- /ai-instructions/cursor.md - Cursor IDE instructions