Updates: Check the release notes for new features and product updates.

REST Resource: phones.agentMessages

Resource: AgentMessage

A message sent from the agent to a user.

JSON representation
{
  "name": string,
  "sendTime": string,
  "contentMessage": {
    object (AgentContentMessage)
  }
}
Fields
name

string

This field is set by the RBM platform. Do not include it when creating an agent message. The field resolves "phones/{E.164}/agentMessages/{messageId}", where {E.164} is the user's phone number in E.164 format and {messageId} is the agent-assigned ID of the agent message.

sendTime

string (Timestamp format)

This field is set by the RBM platform. Do not include it when creating an agent message. The field resolves the time when the message is sent to the user.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

contentMessage

object (AgentContentMessage)

The content of the agent message.

AgentContentMessage

The content of a message sent from the agent to a user.

JSON representation
{
  "suggestions": [
    {
      object (Suggestion)
    }
  ],

  // Union field content can be only one of the following:
  "text": string,
  "fileName": string,
  "richCard": {
    object (RichCard)
  },
  "contentInfo": {
    object (ContentInfo)
  }
  // End of list of possible types for union field content.
}
Fields
suggestions[]

object (Suggestion)

A list of suggested replies and suggested actions that appear as a list of suggestion chips following the associated agent message. Maximum 11 suggestions.

The chips only display when the associated agent message is the most recent message within the conversation (including both agent and user messages). The user can tap a suggested reply to send the text reply back to the agent or tap a suggested action to initiate a native action on the device.

Union field content. The content of the agent message content can be only one of the following:
text

string

Text encoded in UTF-8.

fileName

string

The unique name of a file. The RBM platform returns a file name when an agent uploads a file.

richCard

object (RichCard)

A standalone rich card.

contentInfo

object (ContentInfo)

Information about a file, including the URL of the file and the URL of the file’s thumbnail.

The RBM platform serves content from a cache, but an agent can force the RBM platform to fetch a new version of the content and refresh the cache.

RichCard

A standalone rich card or a carousel of rich cards sent from the agent to the user.

JSON representation
{

  // Union field card can be only one of the following:
  "carouselCard": {
    object (CarouselCard)
  },
  "standaloneCard": {
    object (StandaloneCard)
  }
  // End of list of possible types for union field card.
}
Fields
Union field card. Standalone card or carousel of cards. card can be only one of the following:
carouselCard

object (CarouselCard)

Carousel of cards.

standaloneCard

object (StandaloneCard)

Standalone card.

CarouselCard

Carousel of cards.

JSON representation
{
  "cardWidth": enum (CardWidth),
  "cardContents": [
    {
      object (CardContent)
    }
  ]
}
Fields
cardWidth

enum (CardWidth)

The width of the cards in the carousel.

cardContents[]

object (CardContent)

The list of contents for each card in the carousel. A carousel can have a minimum of 2 cards and a maximum 10 cards.

CardWidth

The width of the cards in the carousel.

Enums
CARD_WIDTH_UNSPECIFIED Not specified.
SMALL 120 DP. Note that tall media cannot be used.
MEDIUM 232 DP.

CardContent

Card content

JSON representation
{
  "title": string,
  "description": string,
  "media": {
    object (Media)
  },
  "suggestions": [
    {
      object (Suggestion)
    }
  ]
}
Fields
title

string

(Optional) Title of the card. Maximum 200 characters.

description

string

(Optional) Description of the card. Maximum 2000 characters.

media

object (Media)

(Optional) Media (image, GIF, video) to include in the card.

suggestions[]

object (Suggestion)

(Optional) List of suggestions to include in the card. Maximum 4 suggestions.

Media

A media file within a rich card.

JSON representation
{
  "height": enum (Height),

  // Union field content can be only one of the following:
  "fileName": string,
  "contentInfo": {
    object (ContentInfo)
  }
  // End of list of possible types for union field content.
}
Fields
height

enum (Height)

The height of the media within a rich card with a vertical layout. For a standalone card with horizontal layout, height is not customizable, and this field is ignored.

Union field content. Media content content can be only one of the following:
fileName

string

The unique name of the file, returned by the RBM platform when the file was uploaded.

contentInfo

object (ContentInfo)

Information about a file, including the URL of the file and the URL of the file’s thumbnail.

The RBM platform serves content from a cache, but an agent can force the RBM platform to fetch a new version of the content and refresh the cache.

ContentInfo

Message containing the content information.

JSON representation
{
  "fileUrl": string,
  "thumbnailUrl": string,
  "forceRefresh": boolean
}
Fields
fileUrl

string

Publicly reachable URL of the file. The RBM platform determines the MIME type of the file from the content-type field in the HTTP headers when the platform fetches the file. The content-type field must be present and accurate in the HTTP response from the URL. Recommended maximum file size of 100 MB.

thumbnailUrl

string

(Optional, for image and video files only) Publicly reachable URL of the thumbnail. Maximum size of 100 kB.

If you don't provide a thumbnail URL, the RBM platform displays a blank placeholder thumbnail until the user's device downloads the file. Depending on the user's setting, the file may not download automatically and may require the user to tap a download button.

forceRefresh

boolean

If set, the RBM platform fetches the file and thumbnail from the specified URLs, even if the platform has cached copies of the file (and/or of the thumbnail).

Height

Media height

Enums
HEIGHT_UNSPECIFIED Not specified.
SHORT 112 DP.
MEDIUM 168 DP.
TALL 264 DP. Not available for rich card carousels when the card width is set to small.

Suggestion

A suggested reply or a suggested action included within a rich card or within a suggestion chip list.

JSON representation
{

  // Union field option can be only one of the following:
  "reply": {
    object (SuggestedReply)
  },
  "action": {
    object (SuggestedAction)
  }
  // End of list of possible types for union field option.
}
Fields
Union field option. A suggested reply or a suggested action option can be only one of the following:
reply

object (SuggestedReply)

Users can tap a suggested reply to send the text reply back to the agent.

action

object (SuggestedAction)

Users can tap a suggested action to initiate the corresponding native action on the device.

SuggestedReply

When tapped, sends the text reply back to the agent.

JSON representation
{
  "text": string,
  "postbackData": string
}
Fields
text

string

Text that is shown in the suggested reply and sent back to the agent when the user taps it. Maximum 25 characters.

postbackData

string

The base64-encoded payload that the agent receives in a user event when the user taps the suggested reply.

SuggestedAction

When tapped, initiates the corresponding native action on the device.

JSON representation
{
  "text": string,
  "postbackData": string,
  "fallbackUrl": string,

  // Union field action can be only one of the following:
  "dialAction": {
    object (DialAction)
  },
  "viewLocationAction": {
    object (ViewLocationAction)
  },
  "createCalendarEventAction": {
    object (CreateCalendarEventAction)
  },
  "openUrlAction": {
    object (OpenUrlAction)
  },
  "shareLocationAction": {
    object (ShareLocationAction)
  },
  "paymentRequestAction": {
    object (PaymentRequestAction)
  }
  // End of list of possible types for union field action.
}
Fields
text

string

Text that is shown in the suggested action. Maximum 25 characters.

postbackData

string

Payload (base64 encoded) that will be sent to the agent in the user event that results when the user taps the suggested action

fallbackUrl

string

(Optional) Fallback URL to use if a client doesn't support a suggested action. Fallback URLs open in new browser windows.

Union field action. The native action initiated on the device when the user taps the suggested action action can be only one of the following:
dialAction

object (DialAction)

Opens the user's default dialer app with the agent-specified phone number filled in.

viewLocationAction

object (ViewLocationAction)

Opens the user's default map app and selects the agent-specified location or searches around the user's location given an agent-specified query.

createCalendarEventAction

object (CreateCalendarEventAction)

Opens the user's default calendar app and starts the new calendar event flow with the agent-specified event data pre-filled.

openUrlAction

object (OpenUrlAction)

Opens the user's default web browser app to the given URL. If the user has an app installed that is registered as the default handler for the URL, then this app will be opened instead, and its icon will be used in the suggested action UI.

shareLocationAction

object (ShareLocationAction)

Opens the RCS app's location chooser so the user can pick a location to send to the agent.

paymentRequestAction

object (PaymentRequestAction)

Sends a payment request from the agent to the user.

DialAction

Opens the user's default dialer app with the agent-specified phone number filled in.

JSON representation
{
  "phoneNumber": string
}
Fields
phoneNumber

string

The phone number in E.164 format, for example, +12223334444.

ViewLocationAction

Opens the user's default map app and selects the agent-specified location or searches around the user's location given an agent-specified query.

JSON representation
{
  "latLong": {
    object (LatLng)
  },
  "label": string,
  "query": string
}
Fields
latLong

object (LatLng)

(Optional) The latitude and longitude of the specified location.

label

string

(Optional) The label of the pin dropped at latLong.

query

string

(Optional, only supported on Android Messages clients) Rather than specify a latLong (and optionally, a label), the agent can instead specify a query string. For default map apps that support search functionality (including Google Maps), tapping this suggested action results in a location search centered around the user's current location. If the query is sufficiently specific, then agents can use it to select any location in the world.

For instance, setting the query string to "Growing Tree Bank" will show all Growing Tree Bank locations in the user's vicinity. Setting the query string to "1600 Amphitheater Parkway, Mountain View, CA 94043" will select that specific address, regardless of the user's location.

LatLng

An object that represents a latitude/longitude pair. This is expressed as a pair of doubles to represent degrees latitude and degrees longitude. Unless specified otherwise, this object must conform to the WGS84 standard. Values must be within normalized ranges.

JSON representation
{
  "latitude": number,
  "longitude": number
}
Fields
latitude

number

The latitude in degrees. It must be in the range [-90.0, +90.0].

longitude

number

The longitude in degrees. It must be in the range [-180.0, +180.0].

CreateCalendarEventAction

Opens the user's default calendar app and starts the new calendar event flow with the agent-specified event data pre-filled.

JSON representation
{
  "startTime": string,
  "endTime": string,
  "title": string,
  "description": string
}
Fields
startTime

string (Timestamp format)

Event start time.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

endTime

string (Timestamp format)

Event end time.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

title

string

Event title.

description

string

Event description.

OpenUrlAction

Opens the user's default web browser app to the specified URL. If the user has an app installed that is registered as the default handler for the URL, then this app will be opened instead, and its icon will be used in the suggested action UI.

JSON representation
{
  "url": string
}
Fields
url

string

URL

ShareLocationAction

Opens the RCS app's location chooser so the user can pick a location to send back to the agent.

PaymentRequestAction

Payment request action.

JSON representation
{
  "requestId": string,
  "expireTime": string,
  "items": [
    {
      object (LineItem)
    }
  ],
  "total": {
    object (LineItem)
  },
  "paymentMethods": [
    {
      object (Method)
    }
  ],
  "expiredMessage": string,
  "completedMessage": string,
  "signature": string
}
Fields
requestId

string

The agent-assigned ID of the payment request. This may be a UUID, as defined in https://tools.ietf.org/html/rfc4122.

expireTime

string (Timestamp format)

(Optional) A timestamp of when the payment request expires. If a payment request expires, the request becomes invalid.

If you specify a timestamp, the RCS-enabled messaging app doesn't verify an expiration time with the RBM agent. If you don't specify a timestamp, the payment request only expires if the agent flags the request as expired via the experation check webhook.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

items[]

object (LineItem)

Payment request line items, including regular items, taxes, sub-total, and shipping.

total

object (LineItem)

The total amount of the payment request. The value must be positive.

paymentMethods[]

object (Method)

Supported payment methods.

expiredMessage

string

Text that replaces the payment request text when the request is expired.

completedMessage

string

Text that replaces the payment request text when the transaction is complete.

signature

string

This field is set by the RBM platform. Do not include it when creating a payment request. The field resolves to a checksum the RBM platform uses to validate the payment request.

LineItem

A line item in a payment request.

JSON representation
{
  "type": enum (Type),
  "label": string,
  "subText": string,
  "amount": {
    object (Money)
  }
}
Fields
type

enum (Type)

The line item type.

label

string

The text for a line item. For example, "Total due".

subText

string

(Optional) Text that is displayed in a smaller font below the line item label.

amount

object (Money)

The amount of the line item. SECONDARY line items may have a negative amount.

Type

Type of line item in a payment request.

Enums
TYPE_UNSPECIFIED Not specified.
PRIMARY A line item that describes a product or service.
SECONDARY A line item that describes a secondary charge, such as

Money

Represents an amount of money with its currency type.

JSON representation
{
  "currencyCode": string,
  "units": string,
  "nanos": integer
}
Fields
currencyCode

string

The three-letter currency code defined in ISO 4217.

units

string (int64 format)

The whole units of the amount. For example if currencyCode is "USD", then 1 unit is one US dollar.

nanos

integer

Number of nano (10^-9) units of the amount. The value must be between -999,999,999 and +999,999,999 inclusive. If units is positive, nanos must be positive or zero. If units is zero, nanos can be positive, zero, or negative. If units is negative, nanos must be negative or zero. For example $-1.75 is represented as units=-1 and nanos=-750,000,000.

Method

Supported payment methods.

JSON representation
{
  "paymentMethod": string,
  "merchantId": string,
  "merchantName": string,
  "supportedCardNetworks": [
    enum (CardNetwork)
  ],
  "supportedCardTypes": [
    enum (CardType)
  ],
  "tokenizationData": {
    object (TokenizationData)
  },
  "allowedCountryCodes": [
    string
  ],
  "billingAddressRequired": boolean,
  "billingAddressFormat": enum (BillingAddressFormat)
}
Fields
paymentMethod

string

The payment method name. You must set this field to "https://paywith.google.com/pay".

merchantId

string

The merchant ID for the supported payment method.

merchantName

string

The merchant name.

supportedCardNetworks[]

enum (CardNetwork)

The supported card networks. For example, ["MASTERCARD", "VISA", "DISCOVER"].

supportedCardTypes[]

enum (CardType)

The supported card types. For example, ["CARD", "TOKENIZED_CARD"].

tokenizationData

object (TokenizationData)

Tokenization information for the payment request.

allowedCountryCodes[]

string

The countries that the payment request is valid in, as ISO-2 country codes. For example, ["US", "MX"].

billingAddressRequired

boolean

Whether or not the user must provide a billing address.

billingAddressFormat

enum (BillingAddressFormat)

The billing address format.

CardNetwork

Supported card networks.

Enums
CARD_NETWORK_UNSPECIFIED Not specified.
AMEX American Express card network.
DISCOVER Discover card network.
JCB JCB card network.
MASTERCARD Mastercard card network.
VISA Visa card network.
INTERAC Interac card network.

CardType

Supported card types.

Enums
CARD_TYPE_UNSPECIFIED Not specified.
CARD A card, supported by Google Pay.
TOKENIZED_CARD Tokenized card, encrypted by Google Pay.

TokenizationData

Tokenization information for the payment request.

JSON representation
{
  "tokenizationType": enum (TokenizationType),
  "parameters": {
    string: string,
    ...
  }
}
Fields
tokenizationType

enum (TokenizationType)

The tokenization type for the payment processing provider.

parameters

map (key: string, value: string)

Tokenization parameters, such as the public key.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

TokenizationType

The tokenization type for the payment processing provider.

Enums
TOKENIZATION_TYPE_UNSPECIFIED Not specified.
PAYMENT_GATEWAY The tokenization type for processing payments with providers that support the Google Pay API.
NETWORK_TOKEN Depreceated: The tokenization type for using a provider with the payment gateway API.
DIRECT The tokenization type for processing payments with Google Pay.

BillingAddressFormat

Possible billing address formats.

Enums
BILLING_ADDRESS_FORMAT_UNSPECIFIED Not specified.
MIN Name, country code, and postal code.
FULL Name, street address, locality, region, country code, and

StandaloneCard

Standalone card

JSON representation
{
  "cardOrientation": enum (CardOrientation),
  "thumbnailImageAlignment": enum (ThumbnailImageAlignment),
  "cardContent": {
    object (CardContent)
  }
}
Fields
cardOrientation

enum (CardOrientation)

Orientation of the card.

thumbnailImageAlignment

enum (ThumbnailImageAlignment)

Image preview alignment for standalone cards with horizontal layout.

cardContent

object (CardContent)

Card content.

CardOrientation

Orientation of the card.

Enums
CARD_ORIENTATION_UNSPECIFIED Not specified.
HORIZONTAL

Horizontal layout.

If a horizontal rich card's object(CardContent) contains the media field, it must also include at least a title, description, or suggestions[] field.

VERTICAL Vertical layout.

ThumbnailImageAlignment

Image preview alignment for standalone cards with horizontal layout.

Enums
THUMBNAIL_IMAGE_ALIGNMENT_UNSPECIFIED Not specified.
LEFT File preview is left-aligned.
RIGHT File preview is right-aligned.

Methods

create

Sends a message from the agent to a user.

delete

Revokes an agent message that has been sent but not yet delivered.