Nesta página, descrevemos os arquivos de dados que o RCS para empresas cria para ajudar as operadoras com faturamento e auditoria. Consulte as perguntas frequentes sobre faturamento para respostas a dúvidas comuns sobre o modelo de faturamento do RCS para empresas.
| Arquivo | Descrição | Quem pode acessar |
|---|---|---|
| Relatório de eventos de faturamento | Relatório agregado de eventos faturáveis entre agentes iniciados e usuários. | Todas as operadoras que estão usando o RCS para empresas. |
| Registro de atividades | Registro de dados brutos da atividade do RCS for Business, incluindo eventos faturáveis. | Operadoras que operam ativamente o RCS para empresas e o serviço RCS do Google de acordo com os próprios Termos de Serviço (TOS). |
Geração de arquivos
Cada arquivo de dados representa um dia de uso do RCS para empresas no Tempo Universal Coordenado (UTC). Os arquivos são gerados diariamente. O processo de geração pode levar várias horas, e o tempo de conclusão pode variar.
Para agentes não conversacionais, os arquivos contêm dados do período de 24 horas imediatamente anterior ao horário de geração do arquivo. Por exemplo, se um relatório de evento de faturamento for gerado às 11h UTC do dia 5 de maio, ele vai conter dados das 11h UTC do dia 4 de maio até as 11h UTC do dia 5 de maio.
Para agentes conversacionais, os arquivos contêm dados do período de 24 horas de um a dois dias antes da geração do arquivo. Por exemplo, se um relatório de evento de faturamento for gerado às 11h UTC de 5 de maio, ele poderá conter dados das 11h UTC de 3 de maio às 11h UTC de 4 de maio.
O motivo do atraso é que a atividade do RCS Business Messaging para agentes de conversação está vinculada a conversas, que podem levar até 48 horas para serem concluídas. Esse atraso permite que o RCS para empresas capture todas as mensagens de uma conversa antes de calcular o evento de faturamento. Para mais informações sobre agentes de conversação, consulte Categorias de faturamento de agentes.
Pontos importantes:
Sem atividade: se não houver atividade na plataforma em um determinado dia, nenhum arquivo será gerado.
Nomeação: a data no nome do arquivo é a data de geração do arquivo, não a data dos dados nele contidos.
Retenção: os arquivos são armazenados por no máximo 63 dias antes de serem excluídos.
É possível usar esses arquivos para atualizar seu data warehouse com as métricas de uso da plataforma mais recentes.
Armazenamento e acesso a arquivos
Os arquivos de dados são criptografados em repouso e em transferência.
Para recuperar arquivos de dados pelo protocolo de transferência segura de arquivos (SFTP), forneça sua chave pública do SFTP. Para gerar chaves, consulte Gerar um par de chaves Secure Shell (SSH) para uma caixa de depósito SFTP.
O servidor SFTP é partnerupload.google.com, e a conexão é feita em um número de porta alto (19321) para aumentar a segurança.
Use o comando a seguir para acessar seus arquivos de dados:
sftp -i <path_to_private_key> -P 19321 <username>@partnerupload.google.com
O Google fornece nomes de usuário da conta nos seguintes formatos:
rbmreports-billableevents-<carrier name>rbmreports-activity-<carrier name>
O Google especifica <carrier name> e fornece uma conta separada para cada tipo de relatório.
Contas separadas são fornecidas para acessar os diferentes tipos de relatórios.
Disponibilidade de arquivos
Se nenhum arquivo de dados tiver sido gerado ainda, você vai encontrar um erro de SFTP semelhante a
remote readdir("/"): No such file or directory, o que é esperado.
Um arquivo não será gerado se não houver tráfego do RCS para empresas a ser informado. Isso significa que pode haver dias em que nenhum arquivo é gerado. Se você precisar de arquivos vazios para agilizar seu processo, entre em contato com rbm-support@google.com.
Relatórios de eventos de faturamento
Os relatórios de eventos de faturamento são registros de eventos de faturamento, que são calculados com base na categoria de faturamento do agente e no tipo de mensagens enviadas. Os relatórios de eventos de faturamento estão disponíveis para todas as operadoras que usam o RCS Business Messaging.
Os relatórios de eventos de faturamento contêm informações confidenciais, mas não informações de identificação pessoal (PII) do usuário, como MSISDN, MSISDN hash ou qualquer identificador exclusivo do usuário.
Categorias de faturamento do agente
Ao criar um agente, o proprietário define a categoria de faturamento com base em como o agente vai interagir com os usuários. A categoria de faturamento não restringe o número ou o tipo de mensagens que um agente pode enviar. mas determina como o agente será cobrado pelas mensagens. As duas principais categorias de faturamento são descritas na tabela a seguir.
| Categoria do faturamento | Tipo de representante | Exemplos de casos de uso | Método de faturamento |
|---|---|---|---|
Não conversacional (Inclui as categorias Mensagem básica e Mensagem única. Observação: não há mais diferença entre essas duas categorias. Um agente em qualquer uma das categorias será faturado como um agente não conversacional.) |
Agentes que enviam principalmente mensagens unidirecionais. |
|
Cobrança por cada mensagem entregue ao usuário. |
| Conversacional | Agentes projetados para trocas de mensagens com os usuários. |
|
Cobrança por conversa: se uma das partes (o agente ou o usuário) responder a uma mensagem da outra parte em até 24 horas, uma conversa será iniciada. Durante a janela de conversa (24 horas após a primeira resposta), o agente e o usuário podem trocar qualquer número de mensagens, e o agente vai receber uma taxa fixa pela conversa. Cobrança por mensagem: Se o agente enviar uma mensagem que o usuário não responder em 24 horas, o agente será cobrado pela mensagem individual, assim como um agente não conversacional. |
O diagrama a seguir mostra um exemplo de uma sessão de faturamento A2P para agentes de conversa:
Agentes de conversação versus não conversacionais
Há duas categorias principais de faturamento: conversacional e não conversacional. A categoria não conversacional inclui as categorias "Mensagem básica" e "Mensagem única", que são funcionalmente idênticas. Um agente em qualquer uma dessas categorias é faturado como um agente não conversacional.
A principal diferença nas categorias de faturamento é entre agentes de conversação e não conversacionais:
Os agentes não conversacionais são cobrados por cada mensagem que entregam ao usuário.
- Essa categoria é ideal para agentes que não esperam respostas frequentes.
Os agentes de conversação são cobrados com uma taxa fixa por conversa, que inclui todas as mensagens trocadas em um período de 24 horas.
- Essa categoria é mais adequada para agentes que participam de conversas com vários turnos com os usuários.
Eventos de faturamento
Cinco tipos diferentes de eventos de faturamento são registrados nos relatórios de eventos de faturamento. Esses eventos incluem mensagens A2P e P2A.
- A2P (aplicativo para pessoa): enviada pela empresa.
- P2A (pessoa para aplicativo): enviado pelo usuário.
A tabela a seguir descreve cada evento de faturamento para agentes não conversacionais e conversacionais.
| Evento | Descrição | Agentes não conversacionais | Agentes de conversação |
|---|---|---|---|
basic_message
|
Mensagem A2P que inclui apenas texto com até 160 caracteres. Se o texto incluir um URL de um site com tags openGraph, a mensagem poderá mostrar uma prévia da imagem, sem custo adicional para o parceiro. | Sempre tratado como um evento de faturamento individual, independente de o usuário responder ou não. | Tratada como um evento de faturamento individual, a menos que o usuário responda em até 24 horas. Nesse caso, a mensagem passa a fazer parte de um a2p_conversation.
|
single_message
|
Uma mensagem A2P com rich media ou apenas texto com mais de 160 caracteres. | Sempre tratado como um evento de faturamento individual, independente de o usuário responder ou não. | Tratada como um evento de faturamento individual, a menos que o usuário responda em até 24 horas. Nesse caso, a mensagem passa a fazer parte de um a2p_conversation.
|
a2p_conversation (iniciada pela empresa)
|
Iniciada quando um usuário responde a uma mensagem A2P em até 24 horas após o recebimento, fora de uma conversa em andamento. | N/A. Agentes não conversacionais nunca geram esse tipo de evento. | Se uma mensagem P2A for entregue em até 24 horas após várias mensagens A2P, apenas a mensagem A2P que precedeu imediatamente a mensagem P2A será usada para iniciar a conversa. Esta mensagem A2P e todas as mensagens entregues nas próximas 24 horas fazem parte do a2p_conversation.
|
p2a_conversation (iniciada pelo usuário)
|
Iniciada quando um agente responde a uma mensagem P2A em até 24 horas após o recebimento, fora de uma conversa em andamento. | N/A. Agentes não conversacionais nunca geram esse tipo de evento. | Se uma mensagem A2P for entregue em até 24 horas após várias mensagens P2A, apenas a mensagem P2A que precedeu imediatamente a mensagem A2P será usada para iniciar a conversa. Esta mensagem P2A e todas as mensagens entregues nas próximas 24 horas fazem parte do p2a_conversation.
|
p2a_message
|
Mensagem P2A de qualquer tipo. | Sempre tratado como um evento de faturamento individual, independente de o agente responder ou não. | Tratada como um evento de faturamento individual, a menos que o agente responda em até 24 horas. |
Eventos de faturamento x categorias de faturamento
Não confunda os eventos de faturamento basic_message e single_message com as categorias de faturamento "Mensagem básica" e "Mensagem única".
Qualquer agente (independente da categoria de faturamento) pode gerar eventos de faturamento
basic_messageesingle_message.As categorias de faturamento "Mensagem básica" e "Mensagem única" são usadas para classificar agentes não conversacionais. Os agentes nessas categorias de faturamento não geram eventos de faturamento de conversação (
a2p_conversationsoup2a_conversations). Em vez disso, eles geram eventos de faturamento individuaisbasic_message,single_messageep2a_message.
Geração de relatórios de faturamento
Somente agentes com tráfego que não é de teste geram eventos de faturamento. A atividade de números de telefone de teste não aparece nos relatórios de eventos de faturamento.
Esses relatórios presumem que os eventos são faturados quando as mensagens são entregues, e não quando são enviadas. Uma mensagem não entregue ou cancelada antes da entrega não aciona um evento de faturamento.
Formato do relatório de faturamento
Os relatórios de eventos de faturamento usam o formato de nome de arquivo
rbm_billable_events_YYYY-MM-DD.csv. A data no nome do arquivo é a data de geração dele.
Cada linha do relatório é um registro que representa um único evento de faturamento. Os campos em um registro são separados por tabulação. Por exemplo, duas conversas A2P com o mesmo agente gerariam dois eventos de faturamento e dois registros no relatório de eventos de faturamento.
Cada registro no relatório contém as seguintes informações para cada evento de faturamento:
| Campo | Formato | Descrição | Exemplo |
|---|---|---|---|
billing_event_id
|
string | Identificador UUID. Um número aleatório gerado para cada novo evento no momento da criação. | 242f1d9f-7c3f-4e5b-ab3f-818f188fa3ff
|
type
|
string | Tipo de evento:
|
single_message
|
agent_id
|
string | Identificador exclusivo do agente que participou do evento. | rbm-welcome-bot@rbm.goog
|
agent_owner
|
string | Endereço de e-mail do proprietário atual da conta de parceiro em que o agente foi criado. | name@aggregator.com
|
billing_party
|
string | Parte que fatura eventos.
|
carrier
|
max_duration_single_message
|
número | Tempo máximo (em horas) permitido para um usuário responder a uma mensagem do
agente antes que a janela de início da conversa seja fechada e a mensagem seja
classificada como um evento single_message.
|
24
|
max_duration_a2p_conversation
|
número | Duração máxima de uma conversa A2P, em horas. Medido a partir da primeira resposta do usuário à mensagem inicial do agente. | 24
|
max_duration_p2a_conversation
|
número | Duração máxima de uma conversa de P2A, em horas. Medido desde a primeira mensagem do usuário na conversa. | 24
|
start_time
|
YYYY-mm-ddTHH:00:00Z | A data/hora UTC em que o evento começou no formato ISO 8601, arredondada para a hora mais próxima.
Mensagens A2P
Mensagens P2A
|
2019-07-25T08:00:00Z
|
duration
|
número | Duração do evento, arredondada para o minuto mais próximo.
Quando o tipo de evento é |
45
|
mt_messages
|
número | Número de mensagens encerradas em dispositivos móveis (A2P) no evento. | 11
|
mo_messages
|
número | Número de mensagens originadas em dispositivos móveis (P2A) no evento. | 9
|
size_kilobytes
|
número | Tamanho de todos os arquivos anexados às mensagens no evento, arredondado para o kilobyte mais próximo (1 kB = 1024 bytes). | 912
|
agent_name
|
string |
Nome do agente que participou do evento. |
XYZ Mobile USA
|
owner_name
|
string | Nome do proprietário atual da conta de parceiro em que o agente foi criado. | XYZ Mobile
|
Exemplo de relatório de evento de faturamento
Um exemplo de arquivo de relatório de faturamento está disponível para download.
Tamanho típico do arquivo
O tamanho de um relatório diário de um parceiro ativo do RCS Business depende da quantidade de atividade gerada na rede da operadora. Por exemplo, se houver 53.000 registros no relatório, o arquivo terá aproximadamente 8 MB.
Registros de atividades
Os registros de atividades fornecem dados brutos sobre a atividade na plataforma RCS Business. É possível usar esses registros para auditar eventos de faturamento e criar eventos personalizados.
Observação: somente o tráfego de números de telefone que não são de testadores é incluído nos registros de atividade.
Como os registros de atividades contêm informações de identificação pessoal (PII), como informações detalhadas de transações e MSISDNs de assinantes, eles só estão disponíveis quando uma operadora usa o RCS de acordo com os próprios Termos de Serviço. Se você tiver tráfego do RCS para empresas nas suas redes e ativar a atividade do RCS com o RCS do Google de acordo com os Termos de Serviço do Google, não terá acesso aos registros de atividade.
Formato do registro de atividades
Os registros de atividade usam o formato de nome de arquivo rbm_activity_YYYY-MM-DD.csv. A data no nome do arquivo é a data de geração dele.
Os campos em um registro são separados por tabulação, e há um registro por linha.
Cada registro no registro de atividades contém os seguintes campos para cada atividade:
| Campo | Formato | Descrição | Exemplo |
|---|---|---|---|
activity_id
|
string | Identificador exclusivo da atividade. | b422e1d3-ac99-442a-853d-a875d5e61762
|
billing_event_id
|
string | Identificador exclusivo do evento de faturamento associado. Pode ficar vazio se a atividade não estiver associada a um evento de faturamento, como um text_message sem um delivery_receipt_event correspondente.
|
91yeb201-7c3b-412b-98d2-b0a0f7abe536
|
agent_id
|
string | Identificador exclusivo do agente. | welcome-bot@rbm.goog
|
user_id
|
string | MSISDN do usuário. | 918369110173
|
direction
|
string | A direção em que a mensagem é enviada:
|
MT
|
time
|
YYYY-mm-ddTHH:MM:SS.SSSZ | Data e hora em que o evento foi enviado à plataforma RCS para empresas no formato UTC. Consulte Carimbos de data/hora. | 2019-07-25T00:29:07.033Z
|
type
|
string | Tipo de atividade:
|
text_message
|
size_bytes
|
string | Tamanho dos arquivos anexados à atividade, em bytes. | 912
|
Carimbos de data/hora
Os carimbos de data/hora nos registros de atividades registram quando um evento foi enviado à plataforma RCS para empresas. Para eventos que entregam conteúdo a um usuário, o evento não será registrado no registro de atividades até que a mensagem seja entregue.
Por exemplo, se uma mensagem do RCS para empresas for enviada a um usuário na quarta-feira às 13h e o destinatário ficar off-line até domingo às 9h, o evento vai aparecer no registro de atividades gerado para domingo, mas o carimbo de data/hora será quarta-feira, 13h.