NewMessage

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/vonage/main/json-schema/vonage-new-message-schema.json",
  "title": "NewMessage",
  "x-generated": "2026-10-08",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/vonage-sms-openapi.yml#/components/schemas/NewMessage",
  "required": [
    "from",
    "to",
    "text"
  ],
  "properties": {
    "api_key": {
      "description": "Your API key. Only required if setting `sig`.",
      "type": "string",
      "minLength": 8,
      "maxLength": 8
    },
    "sig": {
      "description": "The hash of the request parameters in alphabetical order, a timestamp and the signature secret. See [Signing Requests](https://developer.vonage.com/getting-started/concepts/signing-messages) for more details.\nNote: **DO NOT** set an `Authorization` header when using `sig`.\n",
      "type": "string",
      "minLength": 16,
      "maxLength": 60
    },
    "timestamp": {
      "description": "An integer containing the number of seconds since the epoch (this is sometimes also known as UNIX time). Only required if setting `sig`. See [Signing Requests](https://developer.vonage.com/getting-started/concepts/signing-messages) for more details.",
      "type": "integer"
    },
    "from": {
      "description": "The name or number the message should be sent from. Alphanumeric senderID's are not supported in all countries, see [Global Messaging](https://developer.vonage.com/messaging/sms/guides/global-messaging#country-specific-features) for more details. If alphanumeric, spaces will be ignored. Numbers are specified in E.164 format.",
      "type": "string"
    },
    "to": {
      "description": "The number that the message should be sent to. Numbers are specified in E.164 format.",
      "type": "string",
      "minLength": 7,
      "maxLength": 15,
      "pattern": "\\d{7,15}"
    },
    "text": {
      "description": "The body of the message being sent. If your message contains characters that can be encoded according to the GSM Standard and Extended tables then you can set the `type` to `text`. If your message contains characters outside this range, then you will need to set the `type` to `unicode`.",
      "type": "string"
    },
    "ttl": {
      "description": "**Advanced**: The duration in milliseconds the delivery of an SMS will be attempted. By default Vonage attempts delivery for 72 hours, however the maximum effective value depends on the operator and is typically 24 - 48 hours. We recommend this value should be kept at its default or at least 30 minutes.",
      "type": "integer",
      "default": 259200000,
      "minimum": 20000,
      "maximum": 604800000
    },
    "status-report-req": {
      "description": "**Advanced**: Boolean indicating if you like to receive a [Delivery Receipt](/messaging/sms/building-blocks/receive-a-delivery-receipt).",
      "type": "boolean",
      "default": true
    },
    "callback": {
      "description": "**Advanced**: The webhook endpoint the delivery receipt for this sms is sent to. This parameter overrides the webhook endpoint you set in Dashboard. Max 100 characters.",
      "type": "string"
    },
    "message-class": {
      "description": "**Advanced**: The Data Coding Scheme value of the message",
      "type": "integer",
      "enum": [
        0,
        1,
        2,
        3
      ]
    },
    "type": {
      "description": "**Advanced**: The format of the message body",
      "type": "string",
      "enum": [
        "text",
        "binary",
        "unicode"
      ],
      "default": "text"
    },
    "body": {
      "description": "**Advanced**: Hex encoded binary data. Depends on `type` parameter having the value `binary`.",
      "type": "string"
    },
    "udh": {
      "description": "**Advanced**: Your custom Hex encoded [User Data Header](https://en.wikipedia.org/wiki/User_Data_Header). Depends on `type` parameter having the value `binary`.",
      "type": "string"
    },
    "protocol-id": {
      "description": "**Advanced**: The value of the [protocol identifier](https://en.wikipedia.org/wiki/GSM_03.40#Protocol_Identifier) to use. Ensure that the value is aligned with `udh`.",
      "type": "integer"
    },
    "client-ref": {
      "description": "**Advanced**: You can optionally include your own reference of up to 100 characters.",
      "type": "string"
    },
    "account-ref": {
      "description": "**Advanced**: An optional string used to identify separate accounts using the SMS endpoint for billing purposes. To use this feature, please email [support](mailto:${CUSTOMER_SUPPORT_EMAIL})",
      "type": "string"
    },
    "entity-id": {
      "description": "**Advanced**: A string parameter that satisfies regulatory requirements when sending an SMS to specific countries. For more information please refer to the [Country-Specific Outbound SMS Features](https://api.support.vonage.com/hc/en-us/articles/115011781468)",
      "type": "string"
    },
    "content-id": {
      "description": "**Advanced**: A string parameter that satisfies regulatory requirements when sending an SMS to specific countries. For more information please refer to the [Country-Specific Outbound SMS Features](https://api.support.vonage.com/hc/en-us/articles/115011781468)",
      "type": "string"
    },
    "trusted-number": {
      "description": "Setting this parameter to `true` overrides, on a per-message basis, any protections set up via [Fraud Defender](https://developer.vonage.com/en/fraud-defender/overview) (Traffic Rules, SMS Burst Protection, AIT Protection).\n\nThis parameter only has any effect for accounts subscribed to Fraud Defender Premium.\n",
      "type": "boolean",
      "default": false
    },
    "pool-id": {
      "description": "The ID of the Number Pool to use as the sender of this message. If specified, a number from the pool will be used as the `from` number. \nThe `from` parameter is still required even when specifying a `pool-id` and will be used as a fall-back if the number pool cannot be used.\nSee the [Number Pools documentation](https://developer.vonage.com/numbers/number-pools-api/overview) for more information.\n",
      "type": "string"
    }
  }
}