We will be winding down Google Business Messages on July 31, 2024. Read more
here.
Authenticate the user
Stay organized with collections
Save and categorize content based on your preferences.
Agents typically have little insight into the users they communicate with aside
from information users give during a conversation. However, agents can
authenticate users with OAuth
to confirm user identity, personalize conversations, and take actions on behalf
of users.
In this conversation flow, the user chooses to add credits to their account, and
the agent prompts the user to sign in to validate the user's identity, fetch
known information about the user, and place an order for the credits.
- The user begins the conversation with the agent.
Once the user begins typing a response, they send a typing event to the
agent.
{
"agent": "brands/1111/agents/2222",
"conversationId": "3333",
"customAgentId": "oauth",
"requestId": "1234567890",
"userStatus": {
"isTyping": "true",
"createTime": "2020-10-02T15:01:23.045123456Z",
},
"sendTime": "2020-10-02T15:01:24.045123456Z",
}
The user sends "Hi, I'd like to add 5 credits to my account" as a message.
{
"agent": "brands/1111/agents/2222",
"conversationId": "3333",
"customAgentId": "oauth",
"requestId": "123123123",
"message": {
"messageId": "4444",
"name": "conversations/12345/messages/67890",
"text": "Hi, I'd like to add 5 credits to my account",
"createTime": "2020-10-02T15:05:23.045123456Z",
},
"context": {
"entryPoint": "PLACESHEET",
"userInfo": {
"displayName": "Michael",
"userDeviceLocale": "en",
},
"resolvedLocale": "en",
}
"sendTime": "2020-10-02T15:05:24.045123456Z",
}
The agent sends "I can help you with that. Sign into your account to
continue." along with an Authentication request suggestion.
clientId and scopes are defined by the OAuth provider. The agent
generates the codeChallenge value according to the OAuth provider's
requirements.
curl -X POST "https://businessmessages.googleapis.com/v1/conversations/3333/messages" \
-H "Content-Type: application/json" \
-H "`oauth2l header --json path/to/service/account/key.json businessmessages`" \
-d "{
'messageId': '5555',
'text': 'I can help you with that. Sign into your account to continue.',
'suggestions': [
{
'AuthenticationRequest': {
'clientId': 'oauth_client_id_1234567890',
'codeChallenge': 'code_challenge',
'scopes': [
'account',
'billing',
],
},
},
],
'representative': {
'avatarImage': 'https://oauth.agent/bot-avatar.jpg',
'displayName': 'OAuth Agent',
'representativeType': 'BOT'
}
}"
The user receives the message, taps the authentication request suggestion,
and signs into their account.
The agent receives a message with the OAuth authorization code in the
authenticationResponse.code field.
{
"agent": "brands/1111/agents/2222",
"conversationId": "3333",
"customAgentId": "oauth",
"requestId": "1234567895",
"authenticationResponse": {
"code": "fkhoe541658sfk684d135j186mngkjdrt5425415a2s1dfa68s4edf",
},
}
"sendTime": "2020-10-02T15:01:24.045123456Z",
}
The agent communicates with the OAuth provider, exchanging the authorization
code for an access token and fetching the user's account information.
The agent sends "Thanks for signing in. You currently have 2 credits. To
confirm, you'd like me to add 5 credits to your account and bill your
default payment method?" as a message with "Yes" and "No" as suggested replies.
curl -X POST "https://businessmessages.googleapis.com/v1/conversations/3333/messages" \
-H "Content-Type: application/json" \
-H "`oauth2l header --json path/to/service/account/key.json businessmessages`" \
-d "{
'messageId': '7777',
'text': 'Thanks for signing in. You currently have 2 credits. To confirm, you'd like to me to add 5 credits to your account and bill your default payment method?',
'suggestions': [
{
'reply': {
'text': 'Yes',
'postbackData': 'process-transaction',
},
},
{
'reply': {
'text': 'No',
'postbackData': 'cancel-transaction',
},
},
],
'representative': {
'avatarImage': 'https://oauth.agent/bot-avatar.jpg',
'displayName': 'OAuth Agent',
'representativeType': 'BOT'
}
}"
The user taps the "Yes" suggested reply.
{
"agent": "brands/1111/agents/2222",
"conversationId": "3333",
"customAgentId": "oauth",
"requestId": "1234567898",
"suggestionResponse": {
"message": "conversations/333/messages/8888",
"postbackData": "process-transaction",
"createTime": "2020-10-02T15:01:26.045123456Z",
"text": "Yes",
"suggestionType": "REPLY",
}
"sendTime": "2020-10-02T15:01:27.045123456Z",
}
The agent processes the transaction using the OAuth access token, then sends
the message "Great. I just added 5 credits to your account. Is there
anything else I can help you with?".
curl -X POST "https://businessmessages.googleapis.com/v1/conversations/3333/messages" \
-H "Content-Type: application/json" \
-H "`oauth2l header --json path/to/service/account/key.json businessmessages`" \
-d "{
'messageId': '9999',
'text': 'Great. I just added 5 credits to your account. Is there anything else I can help you with?',
'representative': {
'avatarImage': 'https://oauth.agent/bot-avatar.jpg',
'displayName': 'OAuth Agent',
'representativeType': 'BOT'
}
}"
The user sends "No, thanks".
{
"agent": "brands/1111/agents/2222",
"conversationId": "3333",
"customAgentId": "oauth",
"requestId": "123123133",
"message": {
"messageId": "4444",
"name": "conversations/12345/messages/101010",
"text": "No, thanks",
"createTime": "2020-10-02T15:05:23.045123456Z",
},
"context": {
"entryPoint": "PLACESHEET",
"userInfo": {
"displayName": "Michael",
"userDeviceLocale": "en",
},
"resolvedLocale": "en",
}
"sendTime": "2020-10-02T15:05:28.045123456Z",
}
The agent sends "Thanks for contacting us. Have a great day!"
curl -X POST "https://businessmessages.googleapis.com/v1/conversations/3333/messages" \
-H "Content-Type: application/json" \
-H "`oauth2l header --json path/to/service/account/key.json businessmessages`" \
-d "{
'messageId': '11111111',
'text': 'Thanks for contacting us. Have a great day!',
'representative': {
'avatarImage': 'https://oauth.agent/bot-avatar.jpg',
'displayName': 'OAuth Agent',
'representativeType': 'BOT'
}
}"
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-11-14 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-11-14 UTC."],[[["\u003cp\u003eBusiness Messages agents can authenticate users with OAuth to verify their identity and access account information.\u003c/p\u003e\n"],["\u003cp\u003eOAuth authentication allows agents to personalize conversations and perform actions on behalf of users, such as processing transactions.\u003c/p\u003e\n"],["\u003cp\u003eIn this example, a user initiates a credit purchase, the agent requests authentication, and upon successful login, the agent completes the transaction.\u003c/p\u003e\n"],["\u003cp\u003eAgents leverage the OAuth authorization code to obtain an access token and interact with the user's account securely.\u003c/p\u003e\n"]]],[],null,["# Authenticate the user\n\nAgents typically have little insight into the users they communicate with aside\nfrom information users give during a conversation. However, agents can\n[authenticate users with OAuth](/business-communications/business-messages/guides/how-to/integrate/oauth)\nto confirm user identity, personalize conversations, and take actions on behalf\nof users.\n\nIn this conversation flow, the user chooses to add credits to their account, and\nthe agent prompts the user to sign in to validate the user's identity, fetch\nknown information about the user, and place an order for the credits.\n\n1. The user begins the conversation with the agent.\n2. Once the user begins typing a response, they send a typing event to the\n agent.\n\n {\n \"agent\": \"brands/1111/agents/2222\",\n \"conversationId\": \"3333\",\n \"customAgentId\": \"oauth\",\n \"requestId\": \"1234567890\",\n \"userStatus\": {\n \"isTyping\": \"true\",\n \"createTime\": \"2020-10-02T15:01:23.045123456Z\",\n },\n \"sendTime\": \"2020-10-02T15:01:24.045123456Z\",\n }\n\n3. The user sends \"Hi, I'd like to add 5 credits to my account\" as a message.\n\n {\n \"agent\": \"brands/1111/agents/2222\",\n \"conversationId\": \"3333\",\n \"customAgentId\": \"oauth\",\n \"requestId\": \"123123123\",\n \"message\": {\n \"messageId\": \"4444\",\n \"name\": \"conversations/12345/messages/67890\",\n \"text\": \"Hi, I'd like to add 5 credits to my account\",\n \"createTime\": \"2020-10-02T15:05:23.045123456Z\",\n },\n \"context\": {\n \"entryPoint\": \"PLACESHEET\",\n \"userInfo\": {\n \"displayName\": \"Michael\",\n \"userDeviceLocale\": \"en\",\n },\n \"resolvedLocale\": \"en\",\n }\n \"sendTime\": \"2020-10-02T15:05:24.045123456Z\",\n }\n\n4. The agent sends \"I can help you with that. Sign into your account to\n continue.\" along with an Authentication request suggestion.\n\n `clientId` and `scopes` are defined by the OAuth provider. The agent\n generates the `codeChallenge` value according to the OAuth provider's\n requirements. \n\n curl -X POST \"https://businessmessages.googleapis.com/v1/conversations/3333/messages\" \\\n -H \"Content-Type: application/json\" \\\n -H \"`oauth2l header --json path/to/service/account/key.json businessmessages`\" \\\n -d \"{\n 'messageId': '5555',\n 'text': 'I can help you with that. Sign into your account to continue.',\n 'suggestions': [\n {\n 'AuthenticationRequest': {\n 'clientId': 'oauth_client_id_1234567890',\n 'codeChallenge': 'code_challenge',\n 'scopes': [\n 'account',\n 'billing',\n ],\n },\n },\n ],\n 'representative': {\n 'avatarImage': 'https://oauth.agent/bot-avatar.jpg',\n 'displayName': 'OAuth Agent',\n 'representativeType': 'BOT'\n }\n }\"\n\n5. The user receives the message, taps the authentication request suggestion,\n and signs into their account.\n\n6. The agent receives a message with the OAuth authorization code in the\n `authenticationResponse.code` field.\n\n {\n \"agent\": \"brands/1111/agents/2222\",\n \"conversationId\": \"3333\",\n \"customAgentId\": \"oauth\",\n \"requestId\": \"1234567895\",\n \"authenticationResponse\": {\n \"code\": \"fkhoe541658sfk684d135j186mngkjdrt5425415a2s1dfa68s4edf\",\n },\n }\n \"sendTime\": \"2020-10-02T15:01:24.045123456Z\",\n }\n\n7. The agent communicates with the OAuth provider, exchanging the authorization\n code for an access token and fetching the user's account information.\n\n8. The agent sends \"Thanks for signing in. You currently have 2 credits. To\n confirm, you'd like me to add 5 credits to your account and bill your\n default payment method?\" as a message with \"Yes\" and \"No\" as suggested replies.\n\n curl -X POST \"https://businessmessages.googleapis.com/v1/conversations/3333/messages\" \\\n -H \"Content-Type: application/json\" \\\n -H \"`oauth2l header --json path/to/service/account/key.json businessmessages`\" \\\n -d \"{\n 'messageId': '7777',\n 'text': 'Thanks for signing in. You currently have 2 credits. To confirm, you'd like to me to add 5 credits to your account and bill your default payment method?',\n 'suggestions': [\n {\n 'reply': {\n 'text': 'Yes',\n 'postbackData': 'process-transaction',\n },\n },\n {\n 'reply': {\n 'text': 'No',\n 'postbackData': 'cancel-transaction',\n },\n },\n ],\n 'representative': {\n 'avatarImage': 'https://oauth.agent/bot-avatar.jpg',\n 'displayName': 'OAuth Agent',\n 'representativeType': 'BOT'\n }\n }\"\n\n9. The user taps the \"Yes\" suggested reply.\n\n {\n \"agent\": \"brands/1111/agents/2222\",\n \"conversationId\": \"3333\",\n \"customAgentId\": \"oauth\",\n \"requestId\": \"1234567898\",\n \"suggestionResponse\": {\n \"message\": \"conversations/333/messages/8888\",\n \"postbackData\": \"process-transaction\",\n \"createTime\": \"2020-10-02T15:01:26.045123456Z\",\n \"text\": \"Yes\",\n \"suggestionType\": \"REPLY\",\n }\n \"sendTime\": \"2020-10-02T15:01:27.045123456Z\",\n }\n\n10. The agent processes the transaction using the OAuth access token, then sends\n the message \"Great. I just added 5 credits to your account. Is there\n anything else I can help you with?\".\n\n curl -X POST \"https://businessmessages.googleapis.com/v1/conversations/3333/messages\" \\\n -H \"Content-Type: application/json\" \\\n -H \"`oauth2l header --json path/to/service/account/key.json businessmessages`\" \\\n -d \"{\n 'messageId': '9999',\n 'text': 'Great. I just added 5 credits to your account. Is there anything else I can help you with?',\n 'representative': {\n 'avatarImage': 'https://oauth.agent/bot-avatar.jpg',\n 'displayName': 'OAuth Agent',\n 'representativeType': 'BOT'\n }\n }\"\n\n11. The user sends \"No, thanks\".\n\n {\n \"agent\": \"brands/1111/agents/2222\",\n \"conversationId\": \"3333\",\n \"customAgentId\": \"oauth\",\n \"requestId\": \"123123133\",\n \"message\": {\n \"messageId\": \"4444\",\n \"name\": \"conversations/12345/messages/101010\",\n \"text\": \"No, thanks\",\n \"createTime\": \"2020-10-02T15:05:23.045123456Z\",\n },\n \"context\": {\n \"entryPoint\": \"PLACESHEET\",\n \"userInfo\": {\n \"displayName\": \"Michael\",\n \"userDeviceLocale\": \"en\",\n },\n \"resolvedLocale\": \"en\",\n }\n \"sendTime\": \"2020-10-02T15:05:28.045123456Z\",\n }\n\n12. The agent sends \"Thanks for contacting us. Have a great day!\"\n\n curl -X POST \"https://businessmessages.googleapis.com/v1/conversations/3333/messages\" \\\n -H \"Content-Type: application/json\" \\\n -H \"`oauth2l header --json path/to/service/account/key.json businessmessages`\" \\\n -d \"{\n 'messageId': '11111111',\n 'text': 'Thanks for contacting us. Have a great day!',\n 'representative': {\n 'avatarImage': 'https://oauth.agent/bot-avatar.jpg',\n 'displayName': 'OAuth Agent',\n 'representativeType': 'BOT'\n }\n }\""]]