SendMessageRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/envoisms-ma/json-schema/envoisms-ma-send-message-request-schema.json",
  "title": "SendMessageRequest",
  "description": "`message` is required for SMS and for WhatsApp text and interactive messages. A WhatsApp message whose content is a template, a media object, a reaction, contacts, a location or a sticker needs no `message` (for media it becomes the caption when given). Exactly one of reaction, contacts, location or sticker per message, and none of them together with another content type.\n",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/envoisms-ma-api-openapi.json#/components/schemas/SendMessageRequest",
  "type": "object",
  "required": [
    "to"
  ],
  "properties": {
    "to": {
      "type": "string",
      "description": "Destination phone in E.164 format"
    },
    "message": {
      "type": "string",
      "description": "Message content (max 1600 chars). See the object description for when it may be omitted on WhatsApp."
    },
    "from": {
      "type": "string",
      "description": "SMS sender shown to the recipient (3–11 letters, digits or spaces; a generic header such as INFO or a bank name is refused). Omitted, the SMS goes out under the shared sender EnvoiSMS at 0.792 MAD. Your own name works with no registration at 1.70 MAD until it is validated with your RC, then at the standard rate. Aliases: sender_id, sender."
    },
    "channel": {
      "type": "string",
      "enum": [
        "sms",
        "whatsapp",
        "voice",
        "rcs"
      ],
      "default": "sms",
      "description": "Channel for message delivery: sms (default) for Moroccan operator routes; whatsapp to send from your own connected WhatsApp Business number (403 WHATSAPP_NOT_CONNECTED otherwise). To send an ordinary text to a customer who happens to use WhatsApp, sms is enough: no connection, no template, no 24-hour window. On whatsapp, a message that is not a template may only be sent to a contact who wrote to your number in the last 24 hours — otherwise it is refused with 400 OUT_OF_24H_WINDOW before any charge (with a cascade, WhatsApp is skipped and the next channel is used instead)."
    },
    "cascade": {
      "type": "boolean",
      "description": "When true, tries WhatsApp, then falls back to SMS: at once if WhatsApp refuses the message or reports it failed (not on WhatsApp, 24-hour window closed, ...), or when no delivery report arrives within cascade_timeout (120 s by default). Only a send that actually went out is billed: a refused or failed WhatsApp message is not, and you pay for the SMS alone. A WhatsApp message still waiting for its delivery report did go out (it can still be delivered when the phone reconnects), so it is billed along with its SMS fallback, and refunded if WhatsApp later reports it failed. Tip: give your WhatsApp template a time-to-live (TTL) no longer than cascade_timeout, so a phone that comes back online does not receive both.",
      "default": false
    },
    "cascade_timeout": {
      "type": "integer",
      "minimum": 30,
      "maximum": 43200,
      "default": 120,
      "description": "With cascade: seconds to wait for a delivery report before the next channel. Shorter falls back faster but bills more double sends; longer means fewer duplicates. Out of range: 400 INVALID_FIELD."
    },
    "metadata": {
      "type": "object",
      "description": "Custom key-value pairs, stored with the message and returned in DLR webhooks. One key carries platform semantics: set purpose: \"otp\" when the message carries a one-time code you generated yourself — if the network reports a hard delivery failure on a Moroccan number while the code is still fresh (within 10 minutes), the platform automatically re-sends it once over an alternate SMS route, under the same message id and at no extra charge. Prefer /verify/send when you want the whole code lifecycle (generation, delivery cascade, validation, expiry) managed for you. Set no_failover: true to opt out of this automatic re-send entirely — the first delivery attempt's outcome is then final."
    },
    "buttons": {
      "type": "array",
      "description": "Optional WhatsApp interactive buttons (max 3). Only supported on the whatsapp channel.",
      "items": {
        "$ref": "#/$defs/MessageButton"
      }
    },
    "interactive": {
      "type": "object",
      "description": "WhatsApp Cloud API interactive message payload. cta_url: action {name: \"cta_url\", parameters: {display_text (max 20 chars), url}}. location_request_message: body text plus an optional action {name: \"send_location\"}; the contact answers with a location.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "list",
            "button",
            "product",
            "product_list",
            "flow",
            "carousel",
            "order_details",
            "cta_url",
            "location_request_message"
          ]
        },
        "header": {
          "type": "object"
        },
        "body": {
          "type": "object",
          "properties": {
            "text": {
              "type": "string"
            }
          }
        },
        "footer": {
          "type": "object",
          "properties": {
            "text": {
              "type": "string"
            }
          }
        },
        "action": {
          "type": "object"
        }
      }
    },
    "template": {
      "type": "object",
      "description": "WhatsApp only. An approved template of your account; exempt from the 24-hour window. Priced by the template's category as registered on your account.",
      "properties": {
        "name": {
          "type": "string"
        },
        "language": {
          "type": "string"
        },
        "components": {
          "type": "array",
          "items": {
            "type": "object"
          }
        }
      }
    },
    "phone_number_id": {
      "type": "string",
      "description": "WhatsApp only. Which of your connected numbers sends; defaults to your default number."
    },
    "image": {
      "$ref": "#/$defs/WhatsAppMedia"
    },
    "video": {
      "$ref": "#/$defs/WhatsAppMedia"
    },
    "audio": {
      "$ref": "#/$defs/WhatsAppMedia"
    },
    "document": {
      "$ref": "#/$defs/WhatsAppMedia"
    },
    "sticker": {
      "$ref": "#/$defs/WhatsAppMedia"
    },
    "reaction": {
      "type": "object",
      "description": "WhatsApp only. React to a message of the conversation. Not billed. An empty emoji removes your reaction.",
      "required": [
        "message_id",
        "emoji"
      ],
      "properties": {
        "message_id": {
          "type": "string",
          "description": "WhatsApp message id (wamid) of the message you react to"
        },
        "emoji": {
          "type": "string"
        }
      }
    },
    "contacts": {
      "type": "array",
      "maxItems": 20,
      "description": "WhatsApp only. Contact cards (WhatsApp Cloud API contacts object). name.formatted_name is required; allowed keys: name, phones, emails, urls, addresses, org, birthday (YYYY-MM-DD).",
      "items": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "object",
            "required": [
              "formatted_name"
            ],
            "properties": {
              "formatted_name": {
                "type": "string"
              },
              "first_name": {
                "type": "string"
              },
              "last_name": {
                "type": "string"
              }
            }
          },
          "phones": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "phone": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "wa_id": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "location": {
      "type": "object",
      "description": "WhatsApp only. Send a location pin.",
      "required": [
        "latitude",
        "longitude"
      ],
      "properties": {
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        },
        "name": {
          "type": "string"
        },
        "address": {
          "type": "string"
        }
      }
    },
    "context": {
      "type": "object",
      "description": "WhatsApp only. Reply to (quote) an earlier message of the conversation. Works with every type except reaction.",
      "required": [
        "message_id"
      ],
      "properties": {
        "message_id": {
          "type": "string"
        }
      }
    }
  },
  "$defs": {
    "MessageButton": {
      "type": "object",
      "required": [
        "type",
        "text"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "copy",
            "url",
            "call"
          ],
          "description": "Button action type"
        },
        "text": {
          "type": "string",
          "maxLength": 25,
          "description": "Button text label"
        },
        "copy_code": {
          "type": "string",
          "description": "Value to copy (only for copy type)"
        },
        "url": {
          "type": "string",
          "description": "Target URL (only for url type). Must start with http:// or https://"
        },
        "phone_number": {
          "type": "string",
          "description": "Target phone number (only for call type) in E.164 format"
        }
      }
    },
    "WhatsAppMedia": {
      "type": "object",
      "description": "WhatsApp media by exactly one of id (a media id uploaded to WhatsApp) or link (an https URL). caption on image, video and document only; filename on document only.",
      "properties": {
        "id": {
          "type": "string"
        },
        "link": {
          "type": "string"
        },
        "caption": {
          "type": "string",
          "maxLength": 1024
        },
        "filename": {
          "type": "string"
        }
      }
    }
  }
}