Skip to Content
Product Information

SAP Conversational AI: Conversation Logs 2.0

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 July 2021 update.

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, we have 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 and get started with v2 directly. If you’ve been using v1 until now, you have about 4 months to start using the new API instead. During this time if you have any feedback, use cases or major blockers do let us know 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:

1 Comment
You must be Logged on to comment or reply to a post.