Invoke API Parameters

These are the details of the Invoke API, including descriptions and sample usage. The API is composed of these parameters:

For complete examples of the Invoke API, see Invoke API Message Examples.

endUser

The endUser field sets the destination for the RCS message.

Parameter

Description

phoneNumber

The mobile or landline phone number of the end user. This must be in international format but without a leading + symbol. For example, "447700900765" (UK) or "12515550100" (US).

You can only specify one phone number in this request.

Type: string, between six to 16 characters. The phone number must be enclosed within quotes (" ") and must contain only digits.

Required: yes

mobileOperatorId

 

A numeric ID representing the mobile operator as known by OpenMarket.

For a list of mobile operator IDs see Mobile Operator IDs.

Type: integer

Required: no

variables and request

An RCS message is always first formatted using both a variables and a request element. These elements will directly follow the endUser.

rcs and sms

The request element is composed of the elements that form the RCS message and the backup SMS message that's sent if the recipient's handset does not support RCS. It's composed of two elements, rcs and sms.

Parameter

Description

rcs

Indicates the type of RCS to send. It must be text, media, and/or richCard. You can have multiple RCS types, but you must have at least one type specified. See text, media, or richCard for more information..

Type: object

Required: At least one of text, media, or richCard is required.

sms

 

Indicates that an SMS will be sent in the event that an RCS message can't be received by the receiver. This typically occurs if the phone is not RCS-capable. See sms for more information.

Type: object

Required: No

An RCS message is always first formatted using both a variables and request element. These elements will directly follow the endUser .

rcs

The rcs field element further defines the RCS message by indicating what type of RCS message is being sent: text, media, and/or richCard. You can send multiple types, but you must send at least one type.

Parameter

Description

text

Identifies the RCS message as an RCS text message. See text for more information.

Type: object

Required: At least one of text, media, or richCard is required.

media

 

Identifies the RCS message as an RCS media message. An RCS media message can be a video or an image.

Type: object

Required: At least one of text, media, and/or richCard is required.

richCard

Identifies the RCS as a Rich Card.  A Rich Card is a small snippet, usually an image, that's linked to additional actions. For example, a Rich Card can be used to dial a phone number, access a website, or open a map. You can send multiple Rich Cards in a message.

Type: object

Required: At least one of text, media, and/or richCard is required.

order

Sets the order with a messageOrder array for determining which an RCS type is displayed on the recipient's handset if multiple types are sent. If no order is passed, the default order is by media object type: text, media, and then richCard. See messageOrder for more information.

Type: object

Required: No

text

The text element further defines the parameters of an RCS text message.

Parameter

Description

message

Message displayed to the recipient.

Type: string

Required: Yes. The size can be between 1 and 8192 bytes. Message concatenation is not supported. If the size is greater than the allowed limit the message will be rejected.

id

 

The order in which an RCS type is displayed. Each id must then be passed in the order parameter in rcs. The order in which this id is added to the order is the order in which it will display on the recipient's handset. See order in rcs for information about how the id field is used for ordering.

Type: string

Required: No

suggestions

Array of suggestion objects. For example, this could be a link to a website or to place a call. The order of the list of suggestions is determined by their placement in the JSON request. In addition, suggestions for text only appear if text is the last item on the screen.

Type: collection

Required: No

media

The media type further defines an RCS media message. For example, the RCS message might be a JPEG linked to a website.

Parameter

Description

fileUrl

Link to a media file. The full path must be used. The URL must use https:// and must link to a media file in OpenMarket's CMS. See Media Upload API Version 1 for information on uploading media files.

Type: string

Required: Yes

mimeType

 

Indicates the type of media file. For example, this might be image/jpeg.

Type: string

Required: Yes

fileSize

The size of the media file, in bytes. Different mobile operators have different size limits. For example, you might have a JPEG that is 12367 bytes.

Type: integer

Required: Yes. The maximum file size can be no more than 100 mb.

thumbnailURL

The URL to the image thumbnail, if a thumbnail is used. The full path must be used, starting with https://.

Type: string

Required: No

thumbnailMimeType

The image mime type. For example, this might be image/jpeg.

Type: string

Required: Yes, but only if included the thumbnailURL. Otherwise, no.

thumbnailFileSize

The size of the thumbnail image file, in bytes. Different mobile operators have different size limits. For example, you might have JPEG that is 125 bytes.

Type: integer

Required: Yes, but only if you included the thumbnailURL. Otherwise, no. The maximum size of he thumbnail can be no more than 10 kb.

id

Used for ordering the media type. Each id must then be passed in the order parameter in rcs. The order in which this id is added to the order is the order in which it will display on the recipient's handset. See order in rcs for information about how the id field is used for ordering.

Type: string

Required: No

suggestions

Array of suggestion objects. For example, this could be a link to a website or to place a call. The order of the list of suggestions is determined by their placement in the JSON request. In addition, suggestions for media only appear if media is the last item on the screen.

Type: collection

Required: No

richCard

The richCard media type defines one or more "cards" that display on the recipient's handset. These cards can then be associated with actions, such as dialing a phone number, pinning a map location, or accessing a website.

Parameter

Description

cardOrientation

Sets how a rich card is oriented. cardOrientation is used only when a single Rich Card is sent.

Type: string

Required: No. However, if passed, cardOrientation must be one of the following:

  • HORIZONTAL. If this orientation is used, the optimal resolution for the image is 1440x720 (3:4 ratio)
  • VERTICAL. If this orientation is used, the optimal resolution for the image is 764x1024 (3:4 ratio)

imageAlignment

 

Indicates an image on a Rich Card. imageAlignment is used only when a single Rich Card is sent.

Type: string

Required: No. However, if passed, imageAlignment must be one of the following:

  • LEFT
  • RIGHT
cardHeight

The height of a card when used when a single Rich Card is sent or the height of all Carousel Cards.

Type: string

Required: No. However, if passed, cardHeight must be one of the following:

  • SHORT
  • MEDIUM
  • TALL
cardWidth

The width applied to all cards in a Carousel.

Type: string

Required: No. However, if passed, the cardWidth must be one of the following:

  • SMALL
  • MEDIUM
cards

Defines the cards in an array. A single card is treated as a single Rich Card. Multiple cards are treated as a Carousel. See card for more information about this array.

Note: There must be at least one card in this array.

Type: card

Required: Yes

id

The order in which an RCS type is displayed. Each id must then be passed in the order parameter in rcs. The order in which this id is added to the order is the order in which it will display on the recipient's handset. See order in rcs for information about how the id field is used for ordering.

Type: string

Required: No

messageOrder

The messageOrder field sets the display order of text, media, and richCard objects on a recipient's handset.

Parameter

Description

messageOrder

To use the messageOrder parameter, you must set a string for the id parameter of that RCS type. The string must then be added to order in the order in which you want them displayed. When passed in this parameter, each id should be enclosed within double quotes (" "), each id separated by a comma (,). The entire parameter should then be enclosed in brackets ([ ]). For example, if you have a text type with an id of text1, a media type with an id of media1, and an richCard with id of richcard1, you could set the order as ["richcard1", "media1", "text1"]. The RCS type will then display on the recipient's handset in the id order set here.

Type: array of string.

Required: yes, but only if using the order element.

card

card contains the information for a single card, such as specifying a graphic for the card, an action to take when clicking the card, and the descriptive text that appears on the card.

Parameter

Description

title

Text that displays on the card.

Type: string

Required: No. However, if used, you must use UTF-8 encoding. The maximum size of the title should be no more than 200 characters.

description

 

Descriptive text that appears on the card.

Type: string

Required: At least one of description, media, or suggestions is required, but any combination of these three is valid. The maximum number of characters is 2,000.

media

Defines media, such as graphics, that you want to display in a card. For example, this might be an image with a linked URL. See media for more information.

Type: object

Required: At least one of description, media, or suggestions is required, but any combination of these three is valid.

suggestions

Array that of suggestion objects. For example, this might be opening a website or dialing a phone number.

Type: array

Required: At least one of description, media, or suggestions is required. Any combination of these three is valid; however, the maximum number of suggestions for a single richCard is three — for example, this might be three replies, three actions, or two actions and one suggestion. A maximum of two suggestions is allowed for each card in a carousel. See "cardHeight" in richCard for information about carousel cards.

media

media defines the card associated with the Rich Card. This might include displaying the Rich Card with a graphic.

Parameter

Description

fileUrl

Link to a media file. Link to a media file. The full path must be used. The URL must use https:// and must link to a media file in OpenMarket's CMS. See Media Upload API Version 1 for information on uploading media files..

Type: string

Required: Yes

mimeType

 

Indicates the type of media file. For example, this might be image/jpeg.

Type: string

Required: Yes

fileSize

The size of the media file, in bytes. Different mobile operators have different size limits. For example, you might have a JPEG that is 12367 bytes.

Type: integer

Required: Yes

thumbnailURL

The URL to the image thumbnail, if a thumbnail is used. The full path must be used, starting with https://.

Type: string

Required: No

thumbnailMimeType

The image mime type. For example, this might be image/jpeg.

Type: string

Required: No

thumbnailFileSize

The size of the thumbnail image file, in bytes. Different mobile operators have different size limits. For example, you might have a JPEG that is 125 bytes.

Type: integer

Required: Yes

suggestion

suggestion is an object that defines either an action or a reply for the RCS type.

Parameter

Description

action

Defines the action to take for the click action. Each possible action is composed of further information, dependent on the action taken. See action for more information.

Type: object

Required: A suggestion must have either an action or a reply, but at least one.

reply

 

Defines the reply. See reply for more information.

Type: object

Required: A suggestion must have either an action or a reply, but at least one.

reply

A reply prompts the recipient with display text to perform the requested suggestion.

Parameter

Description

displayText

The text displayed to the recipient when the suggestion is a reply.

Type: string

Required: Yes. The maximum number of characters, including white spaces, is 25. We recommend that you use no more than 10 characters as a larger number requires the end user to scroll through the text to read the entire text.

customerData

When passed in a request, this parameter allows information about the tapped reply to be returned to you as an MO that the specific reply was tapped. This MO can include additional information about the customer, such as an MSISDN. For example, a reply might be an option to dial a phone number.

The parameter should be unique for each reply if multiple reply suggestions are included.

Type: string. If you want the response returned as JSON, you must escape quotes with \". For example,"customerData:" { \"phoneNumber\":\"12065551234\"}".

Required: No. However, if this parameter is not passed no information is returned to you.

action

Defines the action to take when the user clicks a media type if an action is defined for suggestions.

Parameter

Description

displayText

Displays the text the recipient sees for that action. For example, this might be Call us!or Reply now.

Type: string

Required: Yes. The maximum number of characters, including white spaces, is 25. We recommend that you use no more than 10 characters as a larger number would require the end user to scroll through the text to read the entire text.

customerData

When passed in a request, this parameter allows information about the tapped action to be returned to you as an MO that the specific action was tapped. This MO can include additional information about the customer, such as an MSISDN. The parameter should be unique for each action if multiple action suggestions are included.

Type: string. If you want the response returned as JSON, you must escape quotes with \". For example, "customerData:"{\"UserClickOnWebsite\"}". Otherwise, for XML use "customerData:" "UserClickOnWebsite".

Required: No. However, if this parameter is not passed no information is returned to you.

urlAction

 

Clickable URL. This parameter is further refined in urlAction.

Type: object

Required: Exactly one of the following is required in the action object:

  • urlAction
  • dialAction
  • locationAction
  • calendarAction

dialAction

 

Links to the phone dialer, allowing the recipient to call the number associated with the dialAction. This parameter is further refined in dialAction.

Type: object

Required: Yes. Must be one of the following:

  • urlAction
  • dialAction
  • locationAction
  • calendarAction

locationAction

 

Links to the location passed into the locationAction, allowing the recipient to open their default map application and see that location. This parameter is further refined in locationAction.

Type: object

Required: Exactly one of the following is required in the action object:

  • urlAction
  • dialAction
  • locationAction
  • calendarAction

calendarAction

 

Links to the recipients calendar, allowing the recipient to add information to their calendar. For example, this might be used if an RCS message is sent reminding the recipient of an appointment. This parameter is further refined in calendarAction.

Type: object

Required: Exactly one of the following is required in the action object:

  • urlAction
  • dialAction
  • locationAction
  • calendarAction

urlAction

urlAction links a URL to the Rich Card. When the user clicks the Rich Card, the website is accessed from the URL added in this parameter.

Parameter

Description

url

Full path to a website. The URL must begin with either http:// or https://

Type: string

Required: Yes

dialAction

dialAction links a phone number to the Rich Card. When the user clicks the Rich Card, the user is prompted to call the number added here.

Parameter

Description

phoneNumber

Phone number to dial. Use an alphanumeric source address using the international E.164 format; <country code> followed by the <national number>. For example, +12223334444.

Type: string

Required: Yes

locationAction

locationAction opens a map on the user's handset, with the location added here pinned to the map.

Parameter

Description

latitude

The latitudinal coordinate.

Type: string

Required: Yes. Must be in the range [-90.0, +90.0].

longitude

The longitudinal coordinate.

Type: string

Required: Yes. Must be in the range [-180.0, +180.0].

label

Text associated with the pin displayed on the map.

Type: string

Required: No

calendarAction

calendarAction prompts the recipient to add a meeting or appointment request to their handset's calendar, using the start and end times added to this parameter.

Parameter

Description

startTime

The beginning time in RFC 3339 UTC Zulu format, accurate to seconds. For example, 2017-10-02T15:01:30Z.

Type: string

Required: Yes

endTime

The ending time in RFC 3339 UTC Zulu format, accurate to seconds. For example, 2017-10-02T16:01:45Z.

Type: string

Required: Yes

title

Text associated with the pin displayed on the map

Type: string

Required: Yes. You must use UTF-8 encoding. The maximum size of the title should be no more than 4096 bytes

description

Description associated with the calendar event.

Type: string

Required: Yes

sms

When used, the sms parameter sends a fallback SMS message in the event the end user's phone does not support RCS. You must first be provisioned to use this feature. When used, sms fallback uses the HTTP Global SMS API. Events related to SMS can then be found in the SMS Activity Search. customerData is not supported in an SMS message.

Note: UTF-8 is the only supported character set for an SMS fallback. If your message content is greater than the supported number of characters, your message is rejected with a v4 HTTP rejected request message. Contact your Account Manager and work with them to split your messages into multiple segments or reduce the number of characters in the message. Please note that if you choose to segment your message, your carrier might charge you for each sent segment.

Parameter

Description

messageContent

The message to be displayed on the recipient's handset.

Type: string

Required: Yes

sourceTon

The MO source address type of number (TON).

Type: string

Required: No. If used, however, valid values are:

  • 1 - phone number, starting with country code

  • 3 - national short code

  • 5 - alphanumeric