This blog post details the changes in SAP CAI Conversation Logs API. What's going away, what's coming and what does it mean for you. These changes are effective with the November 2021 update which is planned during mid-November.
Like any well-designed software development platform SAP Conversational AI provides a rich set of APIs helping you in your bot building journey. We offer APIs to manage your training datasets, manage your bot, test your bot and also monitor your bot conversations. All available APIs are documented for your reference in
SAP API Business Hub.
Shining the spotlight back on our main subject for the blog post,
Conversation Logs API help you explore and monitor various aspects of the conversations that your end users have with your bot.
Past, Present and the Future
Until now, we've provided you with the
/conversations API which allows you to:
- Index conversations for a time range
- Get details for a single conversation.
- Delete a conversation.
Conversation model returned by this API:
Variable |
Type |
Description |
|---|
id |
String |
The conversation’s uuid |
connector |
String |
The connector’s uuid |
channel |
String |
The channel’s uuid |
chatId |
String |
The native ChatId |
createdAt |
String |
The conversation’s creation date |
participants |
Array of Participant |
An array of participants |
messages |
Array of Message |
An array of messages |
We saw an opportunity to improve this API based on customers' feedback. Here are some of the reasons:
- GET /conversations API retrieves a collection of conversation IDs without its details.
- To fetch the details EACH conversation needs to be retrieved independently with GET /conversations/<id>
- Natural Language Understanding (NLU) information is not a part of the response payload and needs to be fetched using /request for every message from a user.
- DELETE conversation API currently only deletes participant data and messages exchanged in a conversation, however other objects like the memory, logs, NLU data are still persisted. We will be providing a single API which is GDPR compliant and erases all the conversation related objects with a single delete by conversation id call, in a future release.
What is Conversation Logs 2.0?
We have released a
new version of Conversation logs API which resolves the above listed problems.
Note, it is a new version altogether and is not designed to be backward compatible.
Main advantages of this version:
- GET /logs/v2/conversations (Available with the July 2021 update)
- A single GET /conversations with time range parameters returns a list of conversations and related details.
- Natural Language Understanding (NLU) information is returned for each message from the user along with the message details.
- Note that the response messages are /dialog format and not the channel specific format.
- DELETE by Conversation ID (planned for a future release)
- GDPR compliant
- All conversation objects removed with a single call.
Sample response payload for GET /logs/v2/conversations:
{
"results": {
"conversations": [
{
"id": "aedfe87b-b897-39a0-9081-bbf61480fde9",
"start_at": "2021-02-05T17:45:17.044Z",
"channel_id": 1bcbe98b-b897-33a0-9031-bbf61480fge9,
"channel_type": null,
"messages": [
{
"connnector_origin": web-client,
"connector_sender_id": p-123,
"message_id": "1ddbe87b-b897-39a0-9031-bbf61480fde9",
"conversation_skill": "greetings",
"input_message_type": "text",
"input_message_content": "{\"content\":\"hello\",\"type\":\"text\"}",
"replies": "[{\"type\":\"text\",\"content\":\"Hi, nice to meet you :)\"}]
"received_at": "2021-02-05T17:45:17.044Z",
"nlp_sentiment": "vpositive",
"nlp_act": command,
"nlp_status": 200,
"intents": [
"greetings"
],
"entities": [],
"nlp_type": loc:mount
}
]
},
]
}
What happens to v1 of Conversation Logs?
With the release of v2 of Conversation Logs API in July 2021, we also deprecated v1 of /conversations API. v1 will be fully removed with the November 2021 release.
What does that mean for you?
If you are a new user of the Conversation Logs API, be aware that v1 is going away with the upcoming
November 2021 release and get started with v2 directly. If you've been using v1 until now, please start replacing it with the new API instead. If you have any feedback, use cases or major blockers do let us know before before our November 2021 release by getting in touch with us through our
SAP Community
What are the changes you need to perform?
To start using the v2 API upon its release, you will need to authorize access for the API at
Settings -> Danger Zone -> Authorize API Access -> Allow read access to /conversations 2.0 API with bot token
For more information about SAP Conversational AI:
