SendMessageRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/osis-co/json-schema/osis-co-send-message-request-schema.json",
  "title": "SendMessageRequest",
  "description": "Say who to send to with to, contact_id, or conversation_id. Then add body, attachments, or both.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/osis-co-openapi.json#/components/schemas/SendMessageRequest",
  "type": "object",
  "properties": {
    "to": {
      "type": "string",
      "description": "Phone number to send to. Required unless you set contact_id or conversation_id. Use E.164, or set default_country for a local number. For RCS, this must be an E.164 number."
    },
    "body": {
      "type": "string",
      "description": "The message text. Required unless you send attachments."
    },
    "conversation_id": {
      "type": "string",
      "description": "A one-on-one or group conversation to send in. Required unless you set to or contact_id. Group messages stay on iMessage and on the group's original line. Text and attachments both work."
    },
    "reply_to_message_id": {
      "type": "string",
      "maxLength": 200,
      "description": "The message to reply to in an iMessage thread. Needs conversation_id. Thread replies stay on iMessage. Changing this on a retry with the same idempotency key returns 409.",
      "minLength": 1
    },
    "channel": {
      "type": "string",
      "enum": [
        "auto",
        "sms",
        "imessage",
        "rcs",
        "whatsapp"
      ],
      "description": "auto (default) tries iMessage, then RCS, then WhatsApp, then SMS, all from the same number. RCS is only tried for plain text sent to a phone number. WhatsApp is only tried for text or files when the number has WhatsApp turned on and the recipient is on WhatsApp. Comms only moves to the next channel when the last one clearly rejected the message. Timeouts and unclear results never cause a second send. If you pick a channel, only that channel is used. RCS needs a supported dedicated line and doesn't work with contact_id, conversation_id, attachments, polls, or thread replies. channel whatsapp needs a number with WhatsApp turned on, in from or line_e164, and carries text up to 4096 characters, attachments, and thread replies."
    },
    "line_e164": {
      "type": "string",
      "description": "The number to send from, in E.164 format. You can also call it from. Agent keys can pick any line attached to the agent. By default, replies use the conversation's line and new messages use the agent's primary line. A workspace key limited to one line can only use that line."
    },
    "from": {
      "type": "string",
      "description": "Another name for line_e164."
    },
    "idempotency_key": {
      "type": "string",
      "description": "Same as the Idempotency-Key header."
    },
    "attachments": {
      "type": "array",
      "maxItems": 32,
      "description": "Files to send, up to 9 MiB total after decoding. Carriers and phones have their own limits too. contentType and dataBase64 also work.",
      "items": {
        "type": "object",
        "required": [
          "filename",
          "data_base64"
        ],
        "properties": {
          "filename": {
            "type": "string",
            "maxLength": 255,
            "minLength": 1
          },
          "content_type": {
            "type": "string",
            "default": "application/octet-stream"
          },
          "data_base64": {
            "type": "string",
            "contentEncoding": "base64",
            "format": "byte"
          }
        }
      },
      "minItems": 1
    },
    "contact_id": {
      "type": "string",
      "description": "A contact you already have. Required unless you set to or conversation_id."
    },
    "default_country": {
      "type": "string",
      "description": "Country code, only needed if the number is local and has no country code."
    },
    "whatsapp_template": {
      "type": "object",
      "description": "Meta-approved template: name, language.code, optional components containing one body with text parameters. Only for channel=whatsapp.",
      "required": [
        "name",
        "language"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "language": {
          "type": "object",
          "required": [
            "code"
          ],
          "properties": {
            "code": {
              "type": "string"
            }
          }
        },
        "components": {
          "type": "array",
          "items": {
            "type": "object"
          }
        }
      }
    }
  }
}