# Send an RCS message

Sends an RCS message.

```http
POST https://api.pozy.ai/v1/rcs/messages
```

- Area: Messaging / RCS
- Auth: Authorization: Bearer pz_live_...

## Header parameters

- `Idempotency-Key` (string)

## Request body

Content type: `application/json`

- `agentId`, string, required
- `to`, string, required
- `text`, string: Up to 3072 characters
- `content`, object
  - one of: Option 1
    - `type`, string, required: One of `text`
    - `text`, string, required: Up to 3072 characters
    - `suggestions`, array of object: Up to 11 items
      - one of: Option 1
        - `type`, string, required: One of `reply`
        - `text`, string, required: Up to 25 characters
        - `postbackData`, string
      - one of: Option 2
        - `type`, string, required: One of `dial`
        - `text`, string, required: Up to 25 characters
        - `phoneNumber`, string, required
        - `postbackData`, string
      - one of: Option 3
        - `type`, string, required: One of `openUrl`
        - `text`, string, required: Up to 25 characters
        - `url`, string (URL), required
        - `application`, string: One of `BROWSER`, `WEBVIEW`. Default `BROWSER`
        - `webviewViewMode`, string: One of `FULL`, `HALF`, `TALL`. Default `FULL`
        - `postbackData`, string
      - one of: Option 4
        - `type`, string, required: One of `viewLocation`
        - `text`, string, required: Up to 25 characters
        - `latitude`, number
        - `longitude`, number
        - `query`, string
        - `label`, string
        - `postbackData`, string
      - one of: Option 5
        - `type`, string, required: One of `shareLocation`
        - `text`, string, required: Up to 25 characters
        - `postbackData`, string
      - one of: Option 6
        - `type`, string, required: One of `calendarEvent`
        - `text`, string, required: Up to 25 characters
        - `startTime`, string (date-time), required
        - `endTime`, string (date-time), required
        - `title`, string, required: Up to 100 characters
        - `description`, string: Up to 500 characters
        - `postbackData`, string
  - one of: Option 2
    - `type`, string, required: One of `media`
    - `media`, object, required
      - `url`, string (URL), required
      - `thumbnailUrl`, string (URL)
      - `height`, string: One of `SHORT`, `MEDIUM`, `TALL`. Default `MEDIUM`
    - `suggestions`, array of object: Up to 11 items
      - one of: Option 1
        - `type`, string, required: One of `reply`
        - `text`, string, required: Up to 25 characters
        - `postbackData`, string
      - one of: Option 2
        - `type`, string, required: One of `dial`
        - `text`, string, required: Up to 25 characters
        - `phoneNumber`, string, required
        - `postbackData`, string
      - one of: Option 3
        - `type`, string, required: One of `openUrl`
        - `text`, string, required: Up to 25 characters
        - `url`, string (URL), required
        - `application`, string: One of `BROWSER`, `WEBVIEW`. Default `BROWSER`
        - `webviewViewMode`, string: One of `FULL`, `HALF`, `TALL`. Default `FULL`
        - `postbackData`, string
      - one of: Option 4
        - `type`, string, required: One of `viewLocation`
        - `text`, string, required: Up to 25 characters
        - `latitude`, number
        - `longitude`, number
        - `query`, string
        - `label`, string
        - `postbackData`, string
      - one of: Option 5
        - `type`, string, required: One of `shareLocation`
        - `text`, string, required: Up to 25 characters
        - `postbackData`, string
      - one of: Option 6
        - `type`, string, required: One of `calendarEvent`
        - `text`, string, required: Up to 25 characters
        - `startTime`, string (date-time), required
        - `endTime`, string (date-time), required
        - `title`, string, required: Up to 100 characters
        - `description`, string: Up to 500 characters
        - `postbackData`, string
  - one of: Option 3
    - `type`, string, required: One of `card`
    - `card`, object, required
      - `title`, string: Up to 200 characters
      - `description`, string: Up to 2000 characters
      - `media`, object
        - `url`, string (URL), required
        - `thumbnailUrl`, string (URL)
        - `height`, string: One of `SHORT`, `MEDIUM`, `TALL`. Default `MEDIUM`
      - `suggestions`, array of object: Up to 4 items
        - one of: Option 1
          - `type`, string, required: One of `reply`
          - `text`, string, required: Up to 25 characters
          - `postbackData`, string
        - one of: Option 2
          - `type`, string, required: One of `dial`
          - `text`, string, required: Up to 25 characters
          - `phoneNumber`, string, required
          - `postbackData`, string
        - one of: Option 3
          - `type`, string, required: One of `openUrl`
          - `text`, string, required: Up to 25 characters
          - `url`, string (URL), required
          - `application`, string: One of `BROWSER`, `WEBVIEW`. Default `BROWSER`
          - `webviewViewMode`, string: One of `FULL`, `HALF`, `TALL`. Default `FULL`
          - `postbackData`, string
        - one of: Option 4
          - `type`, string, required: One of `viewLocation`
          - `text`, string, required: Up to 25 characters
          - `latitude`, number
          - `longitude`, number
          - `query`, string
          - `label`, string
          - `postbackData`, string
        - one of: Option 5
          - `type`, string, required: One of `shareLocation`
          - `text`, string, required: Up to 25 characters
          - `postbackData`, string
        - one of: Option 6
          - `type`, string, required: One of `calendarEvent`
          - `text`, string, required: Up to 25 characters
          - `startTime`, string (date-time), required
          - `endTime`, string (date-time), required
          - `title`, string, required: Up to 100 characters
          - `description`, string: Up to 500 characters
          - `postbackData`, string
    - `orientation`, string: One of `VERTICAL`, `HORIZONTAL`. Default `VERTICAL`
    - `thumbnailAlignment`, string: One of `LEFT`, `RIGHT`. Default `LEFT`
    - `suggestions`, array of object: Up to 11 items
      - one of: Option 1
        - `type`, string, required: One of `reply`
        - `text`, string, required: Up to 25 characters
        - `postbackData`, string
      - one of: Option 2
        - `type`, string, required: One of `dial`
        - `text`, string, required: Up to 25 characters
        - `phoneNumber`, string, required
        - `postbackData`, string
      - one of: Option 3
        - `type`, string, required: One of `openUrl`
        - `text`, string, required: Up to 25 characters
        - `url`, string (URL), required
        - `application`, string: One of `BROWSER`, `WEBVIEW`. Default `BROWSER`
        - `webviewViewMode`, string: One of `FULL`, `HALF`, `TALL`. Default `FULL`
        - `postbackData`, string
      - one of: Option 4
        - `type`, string, required: One of `viewLocation`
        - `text`, string, required: Up to 25 characters
        - `latitude`, number
        - `longitude`, number
        - `query`, string
        - `label`, string
        - `postbackData`, string
      - one of: Option 5
        - `type`, string, required: One of `shareLocation`
        - `text`, string, required: Up to 25 characters
        - `postbackData`, string
      - one of: Option 6
        - `type`, string, required: One of `calendarEvent`
        - `text`, string, required: Up to 25 characters
        - `startTime`, string (date-time), required
        - `endTime`, string (date-time), required
        - `title`, string, required: Up to 100 characters
        - `description`, string: Up to 500 characters
        - `postbackData`, string
  - one of: Option 4
    - `type`, string, required: One of `carousel`
    - `cards`, array of object, required: At least 2 items. Up to 10 items
      - `title`, string: Up to 200 characters
      - `description`, string: Up to 2000 characters
      - `media`, object
        - `url`, string (URL), required
        - `thumbnailUrl`, string (URL)
        - `height`, string: One of `SHORT`, `MEDIUM`, `TALL`. Default `MEDIUM`
      - `suggestions`, array of object: Up to 4 items
        - one of: Option 1
          - `type`, string, required: One of `reply`
          - `text`, string, required: Up to 25 characters
          - `postbackData`, string
        - one of: Option 2
          - `type`, string, required: One of `dial`
          - `text`, string, required: Up to 25 characters
          - `phoneNumber`, string, required
          - `postbackData`, string
        - one of: Option 3
          - `type`, string, required: One of `openUrl`
          - `text`, string, required: Up to 25 characters
          - `url`, string (URL), required
          - `application`, string: One of `BROWSER`, `WEBVIEW`. Default `BROWSER`
          - `webviewViewMode`, string: One of `FULL`, `HALF`, `TALL`. Default `FULL`
          - `postbackData`, string
        - one of: Option 4
          - `type`, string, required: One of `viewLocation`
          - `text`, string, required: Up to 25 characters
          - `latitude`, number
          - `longitude`, number
          - `query`, string
          - `label`, string
          - `postbackData`, string
        - one of: Option 5
          - `type`, string, required: One of `shareLocation`
          - `text`, string, required: Up to 25 characters
          - `postbackData`, string
        - one of: Option 6
          - `type`, string, required: One of `calendarEvent`
          - `text`, string, required: Up to 25 characters
          - `startTime`, string (date-time), required
          - `endTime`, string (date-time), required
          - `title`, string, required: Up to 100 characters
          - `description`, string: Up to 500 characters
          - `postbackData`, string
    - `cardWidth`, string: One of `SMALL`, `MEDIUM`. Default `MEDIUM`
    - `suggestions`, array of object: Up to 11 items
      - one of: Option 1
        - `type`, string, required: One of `reply`
        - `text`, string, required: Up to 25 characters
        - `postbackData`, string
      - one of: Option 2
        - `type`, string, required: One of `dial`
        - `text`, string, required: Up to 25 characters
        - `phoneNumber`, string, required
        - `postbackData`, string
      - one of: Option 3
        - `type`, string, required: One of `openUrl`
        - `text`, string, required: Up to 25 characters
        - `url`, string (URL), required
        - `application`, string: One of `BROWSER`, `WEBVIEW`. Default `BROWSER`
        - `webviewViewMode`, string: One of `FULL`, `HALF`, `TALL`. Default `FULL`
        - `postbackData`, string
      - one of: Option 4
        - `type`, string, required: One of `viewLocation`
        - `text`, string, required: Up to 25 characters
        - `latitude`, number
        - `longitude`, number
        - `query`, string
        - `label`, string
        - `postbackData`, string
      - one of: Option 5
        - `type`, string, required: One of `shareLocation`
        - `text`, string, required: Up to 25 characters
        - `postbackData`, string
      - one of: Option 6
        - `type`, string, required: One of `calendarEvent`
        - `text`, string, required: Up to 25 characters
        - `startTime`, string (date-time), required
        - `endTime`, string (date-time), required
        - `title`, string, required: Up to 100 characters
        - `description`, string: Up to 500 characters
        - `postbackData`, string
- `fallbackText`, string: Up to 3072 characters
- `ttlSeconds`, integer: At least 1

## Example request

```bash
curl -X POST "https://api.pozy.ai/v1/rcs/messages" \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "agentId": "6b99fbd950277956c14bd44d",
  "to": "+14155550123"
}'
```

```ts
import { randomUUID } from "node:crypto";

const res = await fetch("https://api.pozy.ai/v1/rcs/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Idempotency-Key": randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agentId: "6b99fbd950277956c14bd44d",
    to: "+14155550123"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data?.error ?? `Request failed with status ${res.status}`);
console.log(data);
```

```python
import os
import requests

resp = requests.post(
    "https://api.pozy.ai/v1/rcs/messages",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={
        "agentId": "6b99fbd950277956c14bd44d",
        "to": "+14155550123",
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())
```

## Response 200

- `id`, string
- `conversationId`, string
- `status`, string: One of `sent`

```json
{
  "id": "6bfebd43ddc270f6d2c56fc5",
  "conversationId": "6e525f3820fc636aa96d2ee9",
  "status": "sent"
}
```