Billing event reports and activity logs

This page describes the data files that RBM creates to assist carriers with billing and auditing.

File	Description	Who has access
Billing event report	Aggregated report of billable events between launched agents and users.	All carriers with a signed RBM MDA.
Activity log	Raw data log of RBM activity, including billable events.	Carriers with a signed RBM MDA who operate the Google RCS Service under their own Terms of Service (ToS).

File generation

Each data file represents one day of RBM usage in Coordinated Universal Time (UTC). Files are generated daily between 10:00 and 12:00 UTC.

For non-conversational agents, the files contain data from the 24-hour period that immediately preceded the file generation time. For example, if a billing event report is generated at 11:00 UTC on May 5, it will contain data from 11:00 UTC on May 4 to 11:00 UTC on May 5.
For conversational agents, the files contain data from the 24-hour period 1-2 days prior to the file generation time. For example, if a billing event report is generated at 11:00 UTC on May 5, it may contain data from 11:00 UTC on May 3 to 11:00 UTC on May 4.

The reason for the delay is that RBM activity for conversational agents is linked to conversations, which can take up to 48 hours to complete. This delay allows RBM to capture all messages within a conversation before calculating the billing event. For more information about conversational agents, refer to Agent billing categories.

Key points:

No activity: If there's no platform activity on a given day, no file is generated.
Naming: The date in the filename is the file generation date, not the date of the data within.
Retention: Files are stored for a maximum of 30 days before being deleted.

You can use these files to update your data warehouse with the latest platform usage metrics.

File storage and access

Data files are encrypted at rest and in transfer.

To retrieve data files by Secure File Transfer Protocol (SFTP), provide your SFTP public key. To generate keys, see Generate a Secure Shell (SSH) key pair for an SFTP dropbox.

The SFTP server is partnerupload.google.com, and connection is on a high port number (19321) for additional security.

You can use the following command to access your data files:

sftp -i <path_to_private_key> -P 19321 <username>@partnerupload.google.com

Google provides account usernames in the following formats:

rbmreports-billableevents-<carrier name>
rbmreports-activity-<carrier name>

Google specifies <carrier name> and provides separate account for each report type.

Separate accounts are provided for accessing the different report types.

File availability

If no data files have been generated yet, you'll see an SFTP error similar to remote readdir("/"): No such file or directory, which is expected.

A file won't be generated if there is no RBM traffic to report. This means there may be some days when no files are generated. If you need empty files to streamline your process, contact rbm-support@google.com.

Billing event reports

Billing event reports are records of billing events, which are calculated based on the agent's billing category and the type of messages it sends. Billing event reports are available to all carriers who have an RBM MDA in place.

Billing event reports contain confidential information, but no user Personal Identifiable Information (PII), such as MSISDN, hashed MSISDN, or any user unique identifier.

Agent billing categories

When creating an agent, the owner sets its billing category based on how the agent will interact with users. The billing category does not restrict the number or type of messages an agent can send. But it does determine how the agent will be billed for messages. The two main billing categories are described in the following table.

Billing category	Agent type	Example use cases	Billing method
Non-conversational (Includes Basic Message and Single Message categories. Note: There is no longer any difference between these two categories. An agent in either category will be billed as a non-conversational agent.)	Agents that primarily send one-way messages.	OTPs Alerts Promotional offers	Billed for each message delivered to the user.
Conversational	Agents that are designed for back-and-forth exchanges with users.	Finding the right product Booking a ticket Troubleshooting an issue	Billed per conversation: If one party (the agent or user) replies to a message from the other party within 24 hours, a conversation starts. During the conversation window (24 hours after the first reply), the agent and user can exchange any number of messages, and the agent will be billed a fixed rate for the conversation. Billed per message: If the agent delivers a message that the user doesn't reply to within 24 hours, the agent will be billed for the individual message, similar to a non-conversational agent.

Conversational versus non-conversational agents

There are two main billing categories: conversational and non-conversational. The non-conversational category includes the Basic Message and Single Message categories, which are functionally identical. An agent in either of these categories is billed as a non-conversational agent.

The key difference in the billing categories is between conversational and non-conversational agents:

Non-conversational agents are billed for each message they deliver to the user.
- This category is best for agents that don't expect frequent replies.
Conversational agents are billed a flat rate for conversations, which include all messages exchanged within a 24-hour period.
- This category is best for agents that engage in multi-turn conversations with users.

Billing events

Five different types of billing events are recorded in the billing event reports. These events include A2P and P2A messages.

A2P (Application-to-Person): Sent by the business.
P2A (Person-to-Application): Sent by the user.

The following table describes each billing event as it applies to non-conversational and conversational agents.

Event	Description	Non-conversational agents	Conversational agents
`basic_message`	A2P message that includes only text with 160 characters or less. If the text includes a URL for a website with openGraph tags, the message may show an image preview, at no added charge to the partner.	Always treated as an individual billing event, regardless of whether the user replies.	Treated as an individual billing event, unless the user replies within 24 hours. In that case, the message becomes part of an `a2p_conversation`.
`single_message`	A2P message that includes multimedia and/or text with more than 160 characters.	Always treated as an individual billing event, regardless of whether the user replies.	Treated as an individual billing event, unless the user replies within 24 hours. In that case, the message becomes part of an `a2p_conversation`.
`a2p_conversation` (business-initiated)	Initiated when a user responds to an A2P message within 24 hours of receiving it, outside of an existing conversation.	N/A. Non-conversational agents never generate this type of event.	If a P2A message is delivered within 24 hours of multiple A2P messages, only the A2P message that immediately preceded the P2A message is used to initiate the conversation. This A2P message, and any messages delivered within the next 24 hours, are part of the `a2p_conversation`.
`p2a_conversation` (user initiated)	Initiated when an agent responds to a P2A message within 24 hours of receiving it, outside of an existing conversation.	N/A. Non-conversational agents never generate this type of event.	If an A2P message is delivered within 24 hours of multiple P2A messages, only the P2A message that immediately preceded the A2P message is used to initiate the conversation. This P2A message, and any messages delivered within the next 24 hours, are part of the `p2a_conversation`.
`p2a_message`	P2A message of any type.	Always treated as an individual billing event, regardless of whether the agent replies.	Treated as an individual billing event, unless the agent replies within 24 hours.

Billing events versus billing categories

The basic_message and single_message billing events shouldn't be confused with the Basic Message and Single Message billing categories.

Any agent (no matter its billing category) can generate basic_message and single_message billing events.
The Basic Message and Single Message billing categories are used to classify non-conversational agents. Agents in these billing categories don't generate conversational billing events (a2p_conversations or p2a_conversations). Instead, they generate individual basic_message, single_message, and p2a_message billing events.

Billing report generation

Only agents with non-tester traffic generate billing events. Activity from test phone numbers doesn't appear in billing event reports.

These reports assume that events are billed when messages are delivered, not when messages are sent. An undelivered message or a message canceled before delivery doesn't trigger a billing event.

Billing report format

Billing event reports use the filename format rbm_billable_events_YYYY-MM-DD.csv. The date in the filename is the file generation date.

Each line in the report is a record representing a single billing event. Fields within a record are tab separated. For example, two A2P conversations with the same agent would generate two billing events and two records in the billing event report.

Each record in the report contains the following information for each billing event:

Field	Format	Description	Example
`billing_event_id`	string	UUID identifier. A random number generated for each new event at the time it is created.	`242f1d9f-7c3f-4e5b-ab3f-818f188fa3ff`
`type`	string	Type of event: `basic_message` `single_message` `a2p_conversation` `p2a_conversation` `p2a_message`	`single_message`
`agent_id`	string	Unique identifier for the agent that participated in the event.	`rbm-welcome-bot@rbm.goog`
`agent_owner`	string	Email address of the current owner of the partner account where the agent was created.	`name@aggregator.com`
`billing_party`	string	Party who bills for events. google carrier	`carrier`
`max_duration_single_message`	number	Maximum time (in hours) allowed for a user to respond to an agent message before the conversation initiation window closes and the message is classified as a `single_message` event.	`24`
`max_duration_a2p_conversation`	number	Maximum duration of an A2P conversation, in hours. Measured from the first user response to the agent's initial message.	`24`
`max_duration_p2a_conversation`	number	Maximum duration of a P2A conversation, in hours. Measured from the first user message in the conversation.	`24`
`start_time`	YYYY-mm-ddTHH:00:00Z	The UTC date/time the event started in ISO 8601 format rounded to the nearest hour. For `a2p_conversation` and `p2a_conversation` events, this is the time that the conversation started. For `single_message` and `basic_message` events, this is the time that the event took place.	`2019-07-25T08:00:00Z`
`duration`	number	Event duration, rounded to the nearest minute. When the event type is `single_message` or `basic_message`, the value is 0.	`45`
`mt_messages`	number	Number of mobile-terminated (A2P) messages in the event.	`11`
`mo_messages`	number	Number of mobile-originated (P2A) messages in the event.	`9`
`size_kilobytes`	number	Size of all files attached to messages in the event, rounded to the nearest kilobyte (1kB = 1024 bytes).	`912`
`agent_name`	string	Name of the agent that participated in the event.	`XYZ Mobile USA`
`owner_name`	string	Name of the current owner of the partner account where the agent was created.	`XYZ Mobile`

Sample billing event report

A sample billing report file is available for download.

Typical file size

A daily report from an active RBM partner may contain around 53,000 records and be approximately 8Mb in size.

Activity logs

Activity logs provide raw data about activity on the RBM platform. You can use these logs to audit billing events and create custom events.

Because activity logs contain Personal Identifiable Information (PII), such as detailed transaction information and subscriber MSISDNs, they are only available when a carrier is operating RCS under their own Terms of Service. If you have RBM traffic on your networks and enable RCS activity with Google RCS under Google's ToS, you won't have access to activity logs.

Activity log format

Activity logs use the filename format rbm_activity_YYYY-MM-DD.csv. The date in the filename is the file generation date.

Fields in a record are tab separated, and there is one record per line.

Each record in the activity log contains the following fields for each activity:

Field	Format	Description	Example
`activity_id`	string	Unique identifier for the activity.	`b422e1d3-ac99-442a-853d-a875d5e61762`
`billing_event_id`	string	Unique identifier for the associated billing event. Can be empty if the activity is not associated with a billing event, such as a `text_message` without corresponding `delivery_receipt_event`.	`91yeb201-7c3b-412b-98d2-b0a0f7abe536`
`agent_id`	string	Unique identifier for the agent.	`welcome-bot@rbm.goog`
`user_id`	string	MSISDN of the user.	`918369110173`
`direction`	string	The direction where the message is sent: `MT` (mobile terminating) for agent-to-user activities `MO` (mobile originating) for user-to-agent activities	`MT`
`time`	YYYY-mm-ddTHH:MM:SS.SSSZ	Date and time when the event was submitted to the RBM platform in UTC format. See Timestamps.	`2019-07-25T00:29:07.033Z`
`type`	string	Type of activity: `text_message` `file_transfer` `rich_card/carousel` `suggestion_tap` `delivery_receipt_event` `read_receipt_event` `spam_report`	`text_message`
`size_bytes`	string	Size of files attached to the activity, in bytes.	`912`

Timestamps

The timestamps in activity logs record when an event was submitted to the RBM platform. For events that deliver content to a user, the event won't be recorded in the activity log until the message is delivered.

For example, if an RBM message is sent to a user on Wednesday at 13:00, and the recipient is offline until Sunday 9:00, the event will appear in the activity log generated for Sunday, but the timestamp will be Wednesday, 13:00.

FAQ

What is a conversation?

In RBM, a conversation is a series of messages exchanged between a user and a conversational agent during a 24-hour period. Only agents with a Conversational billing category can generate conversations and be charged for these billing events:

A2P conversation: Conversation initiated by the business.
P2A conversation: Conversation initiated by the user.

How conversations work

Start: A conversation begins when one party (the agent or user) responds to a message from the other party within 24 hours of receiving it, outside of any existing conversation.
- A2P conversation: Starts when the user responds to the agent's message.
- P2A conversation: Starts when the agent responds to the user's message.
Conversation window: The conversation remains active for 24 hours after it started. The conversation includes all messages within this 24-hour window, as well as the very first message that was initially responded to.
Billing: Instead of billing for each individual message, conversational agents are billed based on the entire conversation. This means the cost is associated with the conversation thread, not the number of messages within it.

Important:

Conversations don't apply to non-conversational agents. Agents with a Basic Message or Single Message billing category are billed per message, regardless of whether the user replies.
For conversational agents, the generation of billing event reports and activity logs can be delayed by up to two days. This delay allows RBM to capture all messages within a conversation before calculating the billing event.