While each type of integration may have some subtle differences on how replies are handled and sent to back to end users. They all still follow the same basic interaction pattern. These examples show some example scenarios, the API calls you would make, and the events you would receive.
Simple interaction
The example below shows a simple interaction with the GenerativeAgent. We first use the Conversation API to create a conversation, and then call the GenerativeAgent API to analyze a message from the customer.
Request
POST /conversation/v1/conversations
{
"externalId": "33411121",
"agent": {
"externalId": "671",
"name": "agentname"
},
"customer": {
"externalId": "11462",
"name": "customername"
},
"metadata": {
"queue": "some-queue"
},
"timestamp": "2024-01-23T13:41:20Z"
}
Response
Status 200: Successfully created the conversation.
{
"id": "01HMVXRVSA1EGC0CHQTF1X2RN3"
}
Now that we have a Conversation ID, we can use it to analyze a new message from our user, like the following:
Request
POST /generativeagent/v1/analyze
{
"conversationId": "01HMVXRVSA1EGC0CHQTF1X2RN3",
"message": {
"text": "How can I pay my bill?",
"sender": {
"externalId": "11462",
"role": "customer"
},
"timestamp": "2024-01-23T13:43:04Z"
}
}
Response
Status 200: Successfully sent the analyze request and created the new message.
{
"conversationId": "01HMVXRVSA1EGC0CHQTF1X2RN3",
"messageId": "01HMVXSWK8J9RR0PNGNN7Z4FVM"
}
GenerativeAgent Events
As a result of the analyze request, the following sequence of events will be sent to via the SSE stream:
{
generativeAgentMessageId: '116aaf51-8180-47b7-9205-9f61c8799c52',
externalConversationId: '33411121',
conversationId: '01HMVXRVSA1EGC0CHQTF1X2RN3',
type: 'processingStart'
}
{
generativeAgentMessageId: '5c020ad9-4a25-4746-a345-017bb9711dbe',
externalConversationId: '33411121',
conversationId: '01HMVXRVSA1EGC0CHQTF1X2RN3',
type: 'reply',
reply: {
messageId: '01HMVXSZANHNGJ49R83HENDAJB',
text: "I'm happy to help you! One moment please."
}
}
{
generativeAgentMessageId: 'd566fda8-3b7c-42a2-ae39-d08b66397238',
externalConversationId: '33411121',
conversationId: '01HMVXRVSA1EGC0CHQTF1X2RN3',
type: 'reply',
reply: {
messageId: '01HMVXTDR1AT9CNQXPYKKBPJ7F',
text: 'You can pay your bill by calling (XXX) XXX-6094, using the Mobile App, or with a customer service agent over the phone (with a $5 fee).'
}
}
{
generativeAgentMessageId: 'bba4320f-de53-4874-83b4-6c8704d3620c',
externalConversationId: '33411121',
conversationId: '01HMVXRVSA1EGC0CHQTF1X2RN3',
type: 'processingEnd'
}
Conversation with an action that requires confirmation
In this use case, we go through a scenario that requires confirmation before the GenerativeAgent can execute a task on the user’s behalf. Besides showing the payload of the GenerativeAgent Events that are sent from the GenerativeAgent, we also check the conversation state.
We assume there is an existing conversation with ID 01HMSHT9KKHHBRMRKJTFZYRCKZ.
Request
POST /generativeagent/v1/analyze
{
"conversationId": "01HMSHT9KKHHBRMRKJTFZYRCKZ",
"message": {
"text": "hello, how can I reset my router?",
"sender": {
"externalId": "11462",
"role": "customer"
},
"timestamp": "2024-01-21T15:08:50Z"
}
}
Response
Status 200: Successfully sent the analyze request and created the new message.
{
"conversationId": "01HMSHT9KKHHBRMRKJTFZYRCKZ",
"messageId": "01HMSHVZGHAXDZMS722JS1JJJK"
}
GenerativeAgent events
As a result of the analyze request, the following sequence of events will be sent via the SSE stream:
{
generativeAgentMessageId: '33843eb0-10f6-4531-a645-ed9481833301',
externalConversationId: '33411121',
conversationId: '01HMSHT9KKHHBRMRKJTFZYRCKZ',
type: 'processingStart'
}
{
generativeAgentkMessageId: '0ed65d99-215d-48b4-be28-fee936f4757e',
externalConversationId: '33411121',
conversationId: '01HMSHT9KKHHBRMRKJTFZYRCKZ',
type: 'reply',
reply: {
messageId: '01HMSQ946T9E3RCXHPNH1B65ZE',
text: "I'm happy to help you! One moment please."
}
}
{
generativeAgentMessageId: '1121411d-e68e-45d3-bf9e-f2a3db73e7ca',
externalConversationId: '33411121',
conversationId: '01HMSHT9KKHHBRMRKJTFZYRCKZ',
type: 'reply',
reply: {
messageId: '01HMSQ96TWXB5DT4T259FP76RX',
text: "Please say 'CONFIRM' to confirm the router reset. This action cannot be undone."
}
}
{
generativeAgentMessageId: '3c4b0f55-c702-453c-9a76-db591f685213',
externalConversationId: '33411121',
conversationId: '01HMSHT9KKHHBRMRKJTFZYRCKZ',
type: 'processingEnd'
}
From the events above, we can see the GenerativeAgent requires user confirmation before it can proceed.
This can be done through another customer message (analyze API call). Optionally, we can check the current conversation state by calling the GET /state API, before the confirmation is sent:
Request
GET /generativeagent/v1/state?conversationId=01HMSHT9KKHHBRMRKJTFZYRCKZ
Response
Status 200. We see the GenerativeAgent is waiting for confirmation for this conversation.
{
"state": "waitingForConfirmation",
"lastGenerativeAgentMessageId": "3c4b0f55-c702-453c-9a76-db591f685213"
}
Now, the user sends the confirmation message:
Request
POST /generativeagent/v1/analyze
{
"conversationId": "01HMSHT9KKHHBRMRKJTFZYRCKZ",
"message": {
"text": "CONFIRM",
"sender": {
"externalId": "11462",
"role": "customer"
},
"timestamp": "2024-01-21T15:09:10Z"
}
}
Response
Status 200: Successfully sent the analyze request and created the new message.
{
"conversationId": "01HMSHT9KKHHBRMRKJTFZYRCKZ",
"messageId": "01HMVJTR2CPABZ46DM0QK1NS3T"
}
The analyze request triggers the following events:
{
generativeAgentMessageId: 'bae280e8-26c7-4333-ae8f-018e5f7140e9',
externalConversationId: '33411121',
conversationId: '01HMSHT9KKHHBRMRKJTFZYRCKZ',
type: 'processingStart'
}
{
generativeAgentMessageId: '7bcbab42-e64f-4e1b-9ec8-5db343d471e3',
externalConversationId: '33411121',
conversationId: '01HMSHT9KKHHBRMRKJTFZYRCKZ',
type: 'reply',
reply: {
messageId: '01HMSQ946T9E3RCXHPNH1B65ZE',
text: "Please wait while your router is being reset..."
}
}
{
generativeAgentMessageId: 'd0e3cb51-79e4-4b90-8c05-3f345090fbdf',
externalConversationId: '33411121',
conversationId: '01HMSHT9KKHHBRMRKJTFZYRCKZ',
type: 'reply',
reply: {
messageId: '01HMSQ96TWXB5DT4T259FP76RX',
text: "Router successfully reset."
}
}
{
generativeAgentMessageId: '6af4172c-7bb7-4fa7-a338-b73a35be5d1c',
externalConversationId: '33411121',
conversationId: '01HMSHT9KKHHBRMRKJTFZYRCKZ',
type: 'reply',
reply: {
messageId: '01HMSQ96TWXB5DT4T259FP76RX',
text: "If you have any other questions or need further assistance, please don't hesitate to ask."
}
}
{
generativeAgentMessageId: '008a21a0-af04-4ece-8f58-b7a0c82a1115',
externalConversationId: '33411121',
conversationId: '01HMSHT9KKHHBRMRKJTFZYRCKZ',
type: 'processingEnd'
}
Finally, we can optionally check the state again. We see it changed back into “ready”.
Request
GET /generativeagent/v1/state?conversationId=01HMSHT9KKHHBRMRKJTFZYRCKZ
Response
{
"state": "ready",
"lastGenerativeAgentMessageId": "008a21a0-af04-4ece-8f58-b7a0c82a1115"
}
Conversation with authentication
In this scenario, the user tries to take an action that requires authentication first. GenerativeAgent will then ask for authentication via the GenerativeAgent event, which we can also confirm via the State API call. We’ll authenticate and see the GenerativeAgent resuming the task.
We assume there is an existing conversation with ID 01HMW15N6V27Y4V2HRCE0CBZJQ. Please see the first use case to understand how to create a new conversation.
Request
POST /generativeagent/v1/analyze
{
"conversationId": "01HMW15N6V27Y4V2HRCE0CBZJQ",
"message": {
"text": "How much do I owe for my mobile?",
"sender": {
"externalId": "11462",
"role": "customer"
},
"timestamp": "2024-01-23T15:49:37Z"
}
}
Response
Status 200: Successfully sent the analyze request and created the new message.
{
"conversationId": "01HMW15N6V27Y4V2HRCE0CBZJQ",
"messageId": "01HMSHT9KKHHBRMRKJTFZYRCKZ"
}
GenerativeAgent events
As a result of the analyze request, the following sequence of messages will be sent via the SSE stream:
{
generativeAgentMessageId: '309181fd-be58-46fa-91b3-ea49f5f4b3d9',
externalConversationId: '33411121',
conversationId: '01HMW15N6V27Y4V2HRCE0CBZJQ',
type: 'processingStart'
}
{
generativeAgentMessageId: '3122535a-3d0b-4bb5-a0ff-6c26616d2325',
externalConversationId: '33411121',
conversationId: '01HMW15N6V27Y4V2HRCE0CBZJQ',
type: 'reply',
reply: {
messageId: '01HMW172YTTESK1EG6A9Y8QRFZ',
text: "I'm happy to help you! One moment please."
}
}
{
generativeAgentMessageId: '49771949-c26e-49ab-86aa-5259d1a249ab',
externalConversationId: '33411121',
conversationId: '01HMW15N6V27Y4V2HRCE0CBZJQ',
type: 'authenticationRequested'
}
{
generativeAgentMessageId: 'd2d43ac5-e160-40fd-9c5b-773c8f7417e0',
externalConversationId: '33411121',
conversationId: '01HMW15N6V27Y4V2HRCE0CBZJQ',
type: 'processingEnd'
}
We can see the second-to-last message is of type authenticationRequested. This tells us that the GenerativeAgent needs authentication in order to continue.
Additionally, we can check the conversation state, which is waitingForAuth:
Request
GET /generativeagent/v1/state?conversationId=01HMW15N6V27Y4V2HRCE0CBZJQ
Response
Status 200. We see the GenerativeAgent is waiting for confirmation for this conversation.
{
"state": "waitingForAuth",
"lastGenerativeAgentMessageId": "d2d43ac5-e160-40fd-9c5b-773c8f7417e0"
}
Now let’s call the authentication endpoint. Note that the specific format and content of the user credentials must be agreed upon between your organization and your ASAPP account team.
Request
POST /conversation/v1/conversations/01HMW15N6V27Y4V2HRCE0CBZJQ/authenticate
{
"customerExternalId": "33411121",
"auth": {
{{authentication payload}}
}
}
Response
Status 204: Successfully sent the authenticate request no response body is expected.
GenerativeAgent Events
After a successful authenticate request, the GenerativeAgent will resume if it was waiting for auth. In this case, the following sequence of messages is sent via the SSE Stream:
{
generativeAgentMessageId: '07df33e7-8603-4393-8ea2-ac29e35197c9',
externalConversationId: '33411121',
conversationId: '01HMW15N6V27Y4V2HRCE0CBZJQ',
type: 'processingStart'
}
{
generativeAgentMessageId: 'adfe3156-18fe-457b-b726-90c489478c80',
externalConversationId: '33411121',
conversationId: '01HMW15N6V27Y4V2HRCE0CBZJQ',
type: 'reply',
reply: {
messageId: '01HMY19BT31Z4AR05S0M5237EK',
text: "Your current balance for your mobile account is $415.38, with no overdue amount and a past due amount of $10."
}
}
{
generativeAgentMessageId: '3325ea14-5b73-4c7a-9511-a6faebc5c98c',
externalConversationId: '33411121',
conversationId: '01HMW15N6V27Y4V2HRCE0CBZJQ',
type: 'reply',
reply: {
messageId: '01HMY19CCJ9E8ENS34WNTQ29E2',
text: 'There are 26 days remaining in your billing cycle.'
}
}
{
generativeAgentMessageId: '3325ea14-5b73-4c7a-9511-a6faebc5c98c',
externalConversationId: '33411121',
conversationId: '01HMW15N6V27Y4V2HRCE0CBZJQ',
type: 'reply',
reply: {
messageId: '01HMY15DGHYHVHZ5GYAXR1TDWS',
text: 'For more information on your mobile billing, you can visit https:
}
}
{
generativeAgentMessageId: 'd8785903-a680-4db5-a95f-ba9ed64a7aaa',
externalConversationId: '33411121',
conversationId: '01HMW15N6V27Y4V2HRCE0CBZJQ',
type: 'processingEnd'
}
Conversation with transfer to an agent
This example showcases the bot transferring the conversation to an agent (a.k.a. agent escalation).
We assume there is an existing conversation with ID 01HMY50MM3D5JP23NPWXKPQVD4. Please see the first use case to understand how to create a new conversation.
Request
POST /generativeagent/v1/analyze
{
"conversationId": "01HMY50MM3D5JP23NPWXKPQVD4",
"message": {
"text": "Can I talk to a real human?",
"sender": {
"externalId": "11462",
"role": "customer"
},
"timestamp": "2024-01-24T11:35:23Z"
}
}
Response
Status 200: Successfully sent the analyze request and created the new message.
{
"conversationId": "01HMY50MM3D5JP23NPWXKPQVD4",
"messageId": "01HMY5FRHW3B76JSS3BVP1VJJX"
}
GenerativeAgent Events
As a result of the analyze request, the following sequence of messages will be sent via the SSE Stream:
{
generativeAgentMessageId: '233e206d-a444-4736-9a66-1fde75e46df7',
externalConversationId: '33411121',
conversationId: '01HMY50MM3D5JP23NPWXKPQVD4',
type: 'processingStart'
}
{
generativeAgentMessageId: '2925b18f-4140-4312-b071-b56feac86d5a',
externalConversationId: '33411121',
conversationId: '01HMY50MM3D5JP23NPWXKPQVD4',
type: 'reply',
reply: {
messageId: '01HMY5FWAMR5DF3DABGNB5118D',
text: 'Sure, connecting you with an agent.'
}
}
{
generativeAgentMessageId: '42ec4212-02aa-4ac6-94e2-4c8fee24352f',
externalConversationId: '33411121',
conversationId: '01HMY50MM3D5JP23NPWXKPQVD4',
type: 'transferToAgent'
}
{
generativeAgentMessageId: '0deb0eb0-dc75-48e5-80ed-805f14d95e0c',
externalConversationId: '33411121',
conversationId: '01HMY50MM3D5JP23NPWXKPQVD4',
type: 'processingEnd'
}
The second-to-last message is of type transferToAgent. We can also optionally verify the conversation state by calling the state API:
Request
GET /generativeagent/v1/state?conversationId=01HMY50MM3D5JP23NPWXKPQVD4
Response
Status 200. We see the GenerativeAgent is waiting for confirmation for this conversation.
{
"state": "transferredToAgent",
"lastGenerativeAgentMessageId": "0deb0eb0-dc75-48e5-80ed-805f14d95e0c"
}
