Example Interactions
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
- Conversation with an action that requires confirmation
- Conversation with authentication
- Conversation with transfer to an agent
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
Response
Status 200: Successfully created the conversation.
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
Response
Status 200: Successfully sent the analyze request and created the new message.
GenerativeAgent Events
As a result of the analyze request, the following sequence of events will be sent to via the SSE stream:
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
Response
Status 200: Successfully sent the analyze request and created the new message.
GenerativeAgent events
As a result of the analyze request, the following sequence of events will be sent via the SSE stream:
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.
Now, the user sends the confirmation message:
Request
POST /generativeagent/v1/analyze
Response
Status 200: Successfully sent the analyze request and created the new message.
The analyze request triggers the following events:
Finally, we can optionally check the state again. We see it changed back into “ready”.
Request
GET /generativeagent/v1/state?conversationId=01HMSHT9KKHHBRMRKJTFZYRCKZ
Response
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
Response
Status 200: Successfully sent the analyze request and created the new message.
GenerativeAgent events
As a result of the analyze request, the following sequence of messages will be sent via the SSE stream:
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.
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
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:
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
Response
Status 200: Successfully sent the analyze request and created the new message.
GenerativeAgent Events As a result of the analyze request, the following sequence of messages will be sent via the SSE Stream:
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.
Was this page helpful?