This blog post details the upcoming changes in SAP CAI Conversation Logs API. What’s going away, what’s coming and what does it mean for you. These changes will be effective with the update scheduled for July 2021.

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 will be releasing a new version of Conversation logs API which resolves the above listed problems. (We will update the API hub link for v2 API here once it is available, so watch this space) 

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 upcoming 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 will also deprecate 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: