--- title: "Launch IVR Scenario" method: POST path: "/voice/ivr/1/messages" tags: ["channels", "voice", "interactive-voice-response", "manage-ivr-scenarios"] --- # Launch IVR Scenario `POST /voice/ivr/1/messages` ## Request - Base URL: `https://api.infobip.com` (the document declares no server; this is the origin it was published from) - URL: `https://api.infobip.com/voice/ivr/1/messages` - Auth: one of: - OAuth 2 - Client credentials - Token URL: `https://api.infobip.com/auth/1/oauth2/token` - API key in header `Authorization` - API key in header `Authorization` - HTTP basic This method allows you to start an outbound IVR toward a multiple destinations. ## Request body - 13d6cf838c63455fe28fcf6ab1b4447c03d816f87ce89525d3cd759ca08a7b1aLaunchScenarioRequest - `bulkId` string: The ID which uniquely identifies the request. - `messages` 13d6cf838c63455fe28fcf6ab1b4447c03d816f87ce89525d3cd759ca08a7b1aIvrMessage[], required: Array of IVR messages to be sent, one object per every message. - `scenarioId` string, required: Scenario key. - `from` string: Numeric sender ID length should be between 3 and 14 characters. - `destinations` 13d6cf838c63455fe28fcf6ab1b4447c03d816f87ce89525d3cd759ca08a7b1aDestination[], required: Array of message destination addresses. Maximum number of destination addresses is 20k. - `messageId` string: The ID that uniquely identifies the message sent. - `to` string, required: Message destination addresses. Destination address must be in the E.164 standard format (Example: `41793026727`). - `notifyUrl` string: The URL on your callback server on which the Delivery report will be sent. - `notifyContentType` string: Preferred Delivery report content type. Can be `application/json` or `application/xml`. - `notifyContentVersion` integer: Specifies the version of the report model to be sent. Can be `1` ([deprecated version 1](#programmable-communications/voice/receive-voice-delivery-reports-deprecated)) or `2` ([current version 2](#programmable-communications/voice/receive-voice-delivery-reports)). The default is version 2. - `callbackData` string: Additional client's data that will be sent on the notifyUrl. The maximum value is 200 characters. - `validityPeriod` integer: The message validity period shown in minutes. When the period expires, it will not be allowed for the message to be sent. A validity period longer than 48h is not supported (in this case, it will be automatically set to 48h). - `sendAt` string, date-time: Used for scheduled Voice messages (message not to be sent immediately, but at scheduled time). - `retry` 13d6cf838c63455fe28fcf6ab1b4447c03d816f87ce89525d3cd759ca08a7b1aRetry: Used to define if the delivery of the Voice messages should be retried in case the first try doesn't succeed. Additional retries will be made according to the schedule defined by _minPeriod_ and _maxPeriod_ parameters and platform's internal retry logic. If the _minPeriod_ differs _maxPeriod_, delivery will be retried in the following manner: after 1 min, 2 min, 5 min, 10 min, 20 min, 30 min, 1 hour, 2 hours, 4 hours, 8 hours, 16 hours, 24 hours or until maxPeriod is reached. If the retry attempt for the _maxPeriod_ is reached, the _maxPeriod_ will be used for all subsequent retries. If the _minPeriod_ and the _maxPeriod_ are defined as equal values, the period of time between retries will be equal to this value. Message delivery will be retried until the successful delivery or message validity or _maxCount_ value is reached. - `maxCount` integer, required: Specify the maximum number of retry attempts. Maximum value of the maxCount is `4`. If the value is higher than `4`, it will be set to `4`. - `maxPeriod` integer, required: Defines the maximum waiting time (in minutes) after the previous failed attempt to try to deliver the message again. Supported values are 1 min, 2 min, 5 min, 10 min, 20 min, 30 min, 1 hour, 2 hours, 4 hours, 8 hours, 16 hours, 24 hours. If entered a value that isn't from the previous list but that's smaller than 24 hours, it is used the next bigger value from the list. If entered value that is bigger than 24 hours than it is used 24 hours. - `minPeriod` integer, required: Defines the minimal waiting time (in minutes) after the previous failed attempt to try to deliver the message again. Supported values are 1 min, 2 min, 5 min, 10 min, 20 min, 30 min, 1 hour, 2 hours, 4 hours, 8 hours, 16 hours, 24 hours. If entered a value that isn't from the previous list but that's smaller than 24 hours, it is used the next bigger value from the list. If entered value that is bigger than 24 hours than it is used 24 hours. - `ringTimeout` integer: Ringing duration, unless there are no operator limitations. Default value is `45`. Note: There are no limitations on the Voice platform regarding this value, however, most of the operators have their own ring timeout limitations and it is advisable to keep the ringTimeout value up to `45` seconds. - `sendingSpeed` 13d6cf838c63455fe28fcf6ab1b4447c03d816f87ce89525d3cd759ca08a7b1aSendingSpeed: Sending rate defined in number of messages sent per second, minute, hour or day. You may wish to use this to allow your systems or agents to handle large amounts of incoming traffic. Not setting a send speed limit can overwhelm your resources with incoming traffic. If this parameter is defined, _validityPeriod_ is ignored. - `speed` integer: Defines the number of messages that will be sent per specified time unit. - `timeUnit` string: Defines time unit used for calculating sending speed. Possible values: `second`, `minute`, `hour` and `day`. - `parameters` object: The parameters that should be passed to the scenario on execution. - `pause` integer: Indicating period of time in seconds between end user answering the call and message starting to be played. Minimal value is `0` and maximum value is `10` seconds. Default value is `0`. - `deliveryTimeWindow` 13d6cf838c63455fe28fcf6ab1b4447c03d816f87ce89525d3cd759ca08a7b1aDeliveryTimeWindow: Scheduling object that allows setting up detailed time windows in which the message can be sent. Consists of from, to and days properties. Days property is mandatory. From and to properties should be either both included, to allow finer time window granulation or both omitted, to include whole days in the delivery time window. Note: delivery time window is set in UTC timezone. - `days` 13d6cf838c63455fe28fcf6ab1b4447c03d816f87ce89525d3cd759ca08a7b1aDeliveryDay[] - `from` 13d6cf838c63455fe28fcf6ab1b4447c03d816f87ce89525d3cd759ca08a7b1aDeliveryTime, required - `hour` integer - `minute` integer - `to` 13d6cf838c63455fe28fcf6ab1b4447c03d816f87ce89525d3cd759ca08a7b1aDeliveryTime, required - `hour` integer - `minute` integer - `callTimeout` integer: Maximum possible duration of the call to be set, shown in seconds. ## Response `200` successful response - 13d6cf838c63455fe28fcf6ab1b4447c03d816f87ce89525d3cd759ca08a7b1aStandardVoiceResponse - `bulkId` string: The ID that uniquely identifies the request. Bulk ID will be received only when you send a message to more than one destination address. - `messages` 13d6cf838c63455fe28fcf6ab1b4447c03d816f87ce89525d3cd759ca08a7b1aVoiceResponseDetails[]: Array of sent messages, one object per every message. - `to` string: The message destination address. - `status` 13d6cf838c63455fe28fcf6ab1b4447c03d816f87ce89525d3cd759ca08a7b1aSingleMessageStatus: Indicates whether the message is successfully sent, not sent, delivered, not delivered, waiting for delivery or any other possible status. - `groupId` integer: Status group ID. - `groupName` string: Status group name that describes which category the status code belongs to, e.g. PENDING, UNDELIVERABLE, DELIVERED, EXPIRED, REJECTED. - `id` integer: Status ID. - `name` string: Status name. - `description` string: Human-readable description of the status. - `messageId` string: The ID that uniquely identifies the message sent. ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `500`: Internal Server Error --- [API](https://skmtc.dev/infobip/apis/infobip-openapi-specification.md) - [All operations](https://skmtc.dev/infobip/apis/infobip-openapi-specification/llms.txt) - [OpenAPI document](https://skmtc.dev/infobip/apis/infobip-openapi-specification/revisions/9dcbbaf902de?raw)