Text-only GenerativeAgent

You have the option to integrate with GenerativeAgent using only text. This may be helpful if you:

• Have your own Speech-to-Text (STT) and Text-to-Speech (TTS) service.
• Adding GenerativeAgent to a text only channel like SMS or web site chat.

GenerativeAgent works on a loop where you will send text content of the conversation and have GenerativeAgent analyze a conversation, then handle the results from GenerativeAgent.

This process is repeated until GenerativeAgent addresses the user’s needs, or GenerativeAgent is unable to help the user and requests a transfer to agent.

Your text-only integration needs to handle:

• Listening and Handling GenerativeAgent events. Create a single SSE stream where events from all conversations are sent.

• Connecting your chat system and trigger GenerativeAgent.

  1. Create a conversation
  2. Add Messages
  3. Analyze a conversation

This diagram shows the interaction between your server and ASAPP, these steps are explained in more detail below:

​

Before you Begin

Before you start integrating to GenerativeAgent, you need to:

• Get your API Key Id and Secret
• Ensure your API key has been configured to access GenerativeAgent APIs. Reach out to your ASAPP team if you unsure.
• Configure Tasks and Functions.

​

Step 1: Listen and Handle GenerativeAgent Events

GenerativeAgent sends you events during the conversation. All events for all conversations being evaluated by GenerativeAgent are sent through the single Server-Sent-Event (SSE) stream..

To create the SSE stream URL, POST to /streams:

curl -X POST 'https://api.sandbox.asapp.com/generativeagent/v1/streams' \
--header 'asapp-api-id: <API KEY ID>' \
--header 'asapp-api-secret: <API TOKEN>' \
--header 'Content-Type: application/json' \
--data '{}'

A successful request returns 200 and the streaming URL you will reconnect with.

{
   "streamId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
   "streamingUrl": "https://ws-coradnor.asapp.com/push-api/connect/sse?token=token", 
  "messageTypes": [
    "generative-agent-message"
  ]
}

Save the streamId. You will use this later to send the GenerativeAgent events to this SSE stream.

You need to listen and handle these events to enable GenerativeAgent to interact with your users.

​

Step 2: Create a Conversation

A conversation represents a thread of messages between an end user and one or more agents. GenerativeAgent evaluates and responds in a given conversation.

Create a conversation providing your Ids for the conversation and customer:

curl -X POST 'https://api.sandbox.asapp.com/conversation/v1/conversations' \
--header 'asapp-api-id: <API KEY ID>' \
--header 'asapp-api-secret: <API TOKEN>' \
--header 'Content-Type: application/json' \
--data '{ 
  "externalId": "1",
  "customer": {   
    "externalId": "[Your id for the customer]",
    "name": "customer name" 
  },
  "timestamp": "2024-01-23T11:42:42Z"
}'

A successfully created conversation returns a status code of 200 and the conversation’s id. Save the conversation id as it is used when calling GenerativeAgent

{"id":"01HNE48VMKNZ0B0SG3CEFV24WM"}

​

Step 3: Add messages

Whether you are implementing a text based channel or using your own transcription, provide the utterances from your users by creating messages. A message represents a single communication within a conversation.

Create a message providing the text of what your user said:

curl -X POST 'https://api.sandbox.asapp.com/conversation/v1/conversations/01HNE48VMKNZ0B0SG3CEFV24WM/messages' \
--header 'asapp-api-id: <API KEY ID>' \
--header 'asapp-api-secret: <API TOKEN>' \
--header 'Content-Type: application/json' \
--data '{ 
  "text": "Hello, I would like to upgrade my internet plan to GOLD.",
  "sender": {   
    "role": "customer",
    "externalId": "[Your id for the customer]" 
  },
  "timestamp": "2024-01-23T11:42:42Z"
}'

Continue to provide the messages while the conversation progresses.

​

Step 4: Analyze conversation with GenerativeAgent

Once you have the SSE stream connected and are sending messages, you need to engage GenerativeAgent with a given conversation.

To have GenerativeAgent analyze a conversation, make a POST request to  /analyze:

curl -X POST 'https://api.sandbox.asapp.com/generativeagent/v1/analyze' \
--header 'asapp-api-id: <API KEY ID>' \
--header 'asapp-api-secret: <API TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
    "conversationId": "01HNE48VMKNZ0B0SG3CEFV24WM",
    "streamId": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
}'

Make sure to include the streamId created when you started the SSE Stream.

GenerativeAgent evaluates the conversation at that moment of time to determine a response. GenerativeAgent is not aware of any additional messages that are sent while processing.

A successful response returns a 200 and the conversation Id.

{
  "conversationId":"01HNE48VMKNZ0B0SG3CEFV24WM"
}

GenerativeAgent’s response is communicated by the events sent through the SSE stream.

​

Analyze with Message

You have the option to send a message when calling analyze.

curl -X POST 'https://api.sandbox.asapp.com/generativeagent/v1/analyze' \
--header 'asapp-api-id: <API KEY ID>' \
--header 'asapp-api-secret: <API TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
    "conversationId": "01HNE48VMKNZ0B0SG3CEFV24WM",
    "streamId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "message": {
        "text": "hello, can I see my bill?",
        "sender": {
            "externalId": "321",
            "role": "customer"
        },
        "timestamp": "2024-01-23T11:50:50Z"
    }
}'

A successful response returns a 200 status code the id of the conversation and the message that was created.

{
  "conversationId":"01HNE48VMKNZ0B0SG3CEFV24WM",
  "messageId":"01HNE6ZEAC94ENQT1VF2EPZE4Y"
}

​

Next Steps

With your system implemented into GenerativeAgent, sending messages and engage GenerativeAgent, you are ready to use GenerativeAgent.

You may find these other pages helpful in using GenerativeAgent: