RCSMessage

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/telnyx/json-schema/telnyx-rcsmessage-schema.json",
  "title": "RCSMessage",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/telnyx-rcs-api-openapi.yml#/components/schemas/RCSMessage",
  "properties": {
    "agent_id": {
      "description": "RCS Agent ID",
      "type": "string"
    },
    "agent_message": {
      "$ref": "#/$defs/RCSAgentMessage"
    },
    "messaging_profile_id": {
      "description": "A valid messaging profile ID",
      "type": "string"
    },
    "mms_fallback": {
      "$ref": "#/$defs/MMSFallback"
    },
    "sms_fallback": {
      "$ref": "#/$defs/SMSFallback"
    },
    "to": {
      "description": "Phone number in +E.164 format",
      "type": "string"
    },
    "type": {
      "description": "Message type - must be set to \"RCS\"",
      "enum": [
        "RCS"
      ],
      "type": "string"
    },
    "webhook_url": {
      "description": "The URL where webhooks related to this message will be sent.",
      "format": "url",
      "type": "string"
    }
  },
  "required": [
    "agent_id",
    "to",
    "messaging_profile_id",
    "agent_message"
  ],
  "type": "object",
  "$defs": {
    "MMSFallback": {
      "properties": {
        "from": {
          "description": "Phone number in +E.164 format",
          "type": "string"
        },
        "media_urls": {
          "description": "List of media URLs",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "subject": {
          "description": "Subject of the message",
          "type": "string"
        },
        "text": {
          "description": "Text",
          "type": "string"
        }
      },
      "type": "object"
    },
    "RCSAction": {
      "description": "When tapped, initiates the corresponding native action on the device.",
      "properties": {
        "create_calendar_event_action": {
          "$ref": "#/$defs/RCSCreateCalendarEventAction"
        },
        "dial_action": {
          "$ref": "#/$defs/RCSDialAction"
        },
        "fallback_url": {
          "description": "Fallback URL to use if a client doesn't support a suggested action. Fallback URLs open in new browser windows. Maximum 2048 characters.",
          "format": "url",
          "type": "string"
        },
        "open_url_action": {
          "$ref": "#/$defs/RCSOpenUrlAction"
        },
        "postback_data": {
          "description": "Payload (base64 encoded) that will be sent to the agent in the user event that results when the user taps the suggested action. Maximum 2048 characters.",
          "type": "string"
        },
        "share_location_action": {
          "$ref": "#/$defs/RCSShareLocationAction"
        },
        "text": {
          "description": "Text that is shown in the suggested action. Maximum 25 characters.",
          "type": "string"
        },
        "view_location_action": {
          "$ref": "#/$defs/RCSViewLocationAction"
        }
      },
      "type": "object"
    },
    "RCSAgentMessage": {
      "properties": {
        "content_message": {
          "$ref": "#/$defs/RCSContentMessage"
        },
        "event": {
          "$ref": "#/$defs/RCSEvent"
        },
        "expire_time": {
          "description": "Timestamp in UTC of when this message is considered expired",
          "format": "date-time",
          "type": "string"
        },
        "ttl": {
          "description": "Duration in seconds ending with 's'",
          "type": "string"
        }
      },
      "type": "object"
    },
    "RCSCardContent": {
      "properties": {
        "description": {
          "description": "Description of the card (at most 2000 characters)",
          "type": "string"
        },
        "media": {
          "$ref": "#/$defs/RCSMedia"
        },
        "suggestions": {
          "description": "List of suggestions to include in the card. Maximum 10 suggestions.",
          "items": {
            "$ref": "#/$defs/RCSSuggestion"
          },
          "type": "array"
        },
        "title": {
          "description": "Title of the card (at most 200 characters)",
          "type": "string"
        }
      },
      "type": "object"
    },
    "RCSCarouselCard": {
      "description": "Carousel of cards.",
      "properties": {
        "card_contents": {
          "description": "The list of contents for each card in the carousel. A carousel can have a minimum of 2 cards and a maximum 10 cards.",
          "items": {
            "$ref": "#/$defs/RCSCardContent"
          },
          "type": "array"
        },
        "card_width": {
          "description": "The width of the cards in the carousel.",
          "enum": [
            "CARD_WIDTH_UNSPECIFIED",
            "SMALL",
            "MEDIUM"
          ],
          "type": "string"
        }
      },
      "required": [
        "card_width",
        "card_contents"
      ],
      "type": "object"
    },
    "RCSContentInfo": {
      "properties": {
        "file_url": {
          "description": "Publicly reachable URL of the file.",
          "format": "url",
          "type": "string"
        },
        "force_refresh": {
          "description": "If set the URL content will not be cached.",
          "type": "boolean"
        },
        "thumbnail_url": {
          "description": "Publicly reachable URL of the thumbnail. Maximum size of 100 kB.",
          "format": "url",
          "type": "string"
        }
      },
      "required": [
        "file_url"
      ],
      "type": "object"
    },
    "RCSContentMessage": {
      "properties": {
        "content_info": {
          "$ref": "#/$defs/RCSContentInfo"
        },
        "rich_card": {
          "$ref": "#/$defs/RCSRichCard"
        },
        "suggestions": {
          "description": "List of suggested actions and replies",
          "items": {
            "$ref": "#/$defs/RCSSuggestion"
          },
          "type": "array"
        },
        "text": {
          "description": "Text (maximum 3072 characters)",
          "type": "string"
        }
      },
      "type": "object"
    },
    "RCSCreateCalendarEventAction": {
      "description": "Opens the user's default calendar app and starts the new calendar event flow with the agent-specified event data pre-filled.",
      "properties": {
        "description": {
          "description": "Event description. Maximum 500 characters.",
          "type": "string"
        },
        "end_time": {
          "format": "date-time",
          "type": "string"
        },
        "start_time": {
          "format": "date-time",
          "type": "string"
        },
        "title": {
          "description": "Event title. Maximum 100 characters.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "RCSDialAction": {
      "description": "Opens the user's default dialer app with the agent-specified phone number filled in.",
      "properties": {
        "phone_number": {
          "description": "Phone number in +E.164 format",
          "type": "string"
        }
      },
      "required": [
        "phone_number"
      ],
      "type": "object"
    },
    "RCSEvent": {
      "description": "RCS Event to send to the recipient",
      "properties": {
        "event_type": {
          "enum": [
            "TYPE_UNSPECIFIED",
            "IS_TYPING",
            "READ"
          ],
          "type": "string"
        }
      },
      "type": "object"
    },
    "RCSLatLng": {
      "properties": {
        "latitude": {
          "description": "The latitude in degrees. It must be in the range [-90.0, +90.0].",
          "type": "number"
        },
        "longitude": {
          "description": "The longitude in degrees. It must be in the range [-180.0, +180.0].",
          "type": "number"
        }
      },
      "required": [
        "latitude",
        "longitude"
      ],
      "type": "object"
    },
    "RCSMedia": {
      "description": "A media file within a rich card.",
      "properties": {
        "content_info": {
          "$ref": "#/$defs/RCSContentInfo"
        },
        "height": {
          "description": "The height of the media within a rich card with a vertical layout. For a standalone card with horizontal layout, height is not customizable, and this field is ignored.",
          "enum": [
            "HEIGHT_UNSPECIFIED",
            "SHORT",
            "MEDIUM",
            "TALL"
          ],
          "type": "string"
        }
      },
      "type": "object"
    },
    "RCSOpenUrlAction": {
      "description": "Opens the user's default web browser app to the specified URL.",
      "properties": {
        "application": {
          "description": "URL open application, browser or webview.",
          "enum": [
            "OPEN_URL_APPLICATION_UNSPECIFIED",
            "BROWSER",
            "WEBVIEW"
          ],
          "type": "string"
        },
        "description": {
          "description": "Accessbility description for webview.",
          "type": "string"
        },
        "url": {
          "format": "url",
          "type": "string"
        },
        "webview_view_mode": {
          "enum": [
            "WEBVIEW_VIEW_MODE_UNSPECIFIED",
            "FULL",
            "HALF",
            "TALL"
          ],
          "type": "string"
        }
      },
      "required": [
        "url",
        "application",
        "webview_view_mode"
      ],
      "type": "object"
    },
    "RCSReply": {
      "properties": {
        "postback_data": {
          "description": "Payload (base64 encoded) that will be sent to the agent in the user event that results when the user taps the suggested action. Maximum 2048 characters.",
          "type": "string"
        },
        "text": {
          "description": "Text that is shown in the suggested reply (maximum 25 characters)",
          "type": "string"
        }
      },
      "type": "object"
    },
    "RCSRichCard": {
      "properties": {
        "carousel_card": {
          "$ref": "#/$defs/RCSCarouselCard"
        },
        "standalone_card": {
          "$ref": "#/$defs/RCSStandaloneCard"
        }
      },
      "type": "object"
    },
    "RCSShareLocationAction": {
      "description": "Opens the RCS app's location chooser so the user can pick a location to send back to the agent.",
      "type": "object"
    },
    "RCSStandaloneCard": {
      "description": "Standalone card",
      "properties": {
        "card_content": {
          "$ref": "#/$defs/RCSCardContent"
        },
        "card_orientation": {
          "description": "Orientation of the card.",
          "enum": [
            "CARD_ORIENTATION_UNSPECIFIED",
            "HORIZONTAL",
            "VERTICAL"
          ],
          "type": "string"
        },
        "thumbnail_image_alignment": {
          "description": "Image preview alignment for standalone cards with horizontal layout.",
          "enum": [
            "THUMBNAIL_IMAGE_ALIGNMENT_UNSPECIFIED",
            "LEFT",
            "RIGHT"
          ],
          "type": "string"
        }
      },
      "required": [
        "card_orientation",
        "thumbnail_image_alignment",
        "card_content"
      ],
      "type": "object"
    },
    "RCSSuggestion": {
      "properties": {
        "action": {
          "$ref": "#/$defs/RCSAction"
        },
        "reply": {
          "$ref": "#/$defs/RCSReply"
        }
      },
      "type": "object"
    },
    "RCSViewLocationAction": {
      "description": "Opens the user's default map app and selects the agent-specified location.",
      "properties": {
        "label": {
          "description": "The label of the pin dropped",
          "type": "string"
        },
        "lat_long": {
          "$ref": "#/$defs/RCSLatLng"
        },
        "query": {
          "description": "query string (Android only)",
          "type": "string"
        }
      },
      "type": "object"
    },
    "SMSFallback": {
      "properties": {
        "from": {
          "description": "Phone number in +E.164 format",
          "type": "string"
        },
        "text": {
          "description": "Text (maximum 3072 characters)",
          "type": "string"
        }
      },
      "type": "object"
    }
  }
}