Conversations | Your Guide to Migrating from V2 to V3

Hi there,

the following guide to help you migrate to the Conversations API V3. The new version brings exciting features that we are thrilled to announce, yet some of them are not compatible with V2. The new harmonized structures and more editable callbacks will help you get more out of the API than previous versions did.

You will learn all breaking changes and how to fix them. With the new Conversations API V3, you can communicate even faster and easier across all supported channels.

Quick Overview

The main differences are:

  • Multi-channels are no longer supported.
  • The from parameter is moved to the top-level object.
  • Message history endpoint is changed to events.
  • Channel-specific structures are replaced by the harmonized content structure.
  • The media container object is replaced with a simplified model.
  • The userContext is replaced with a simplified model.
  • The get message endpoint is no longer supported.
  • Bulk messages are now configured on the messages object instead of channelType.
  • Applications are replaced by Configurations.
  • WhatsApp template object now defines the header, body, footer, and buttons sections.

Read more about these changes in the V3 Release notes. If you want to try out the new version, you can use our Conversations V3 Postman Collection. We suggest using it together with the corresponding Conversations V3 Postman Environment. 

Migrating: Changes regarding all channels

Multiple channels are changed to single channel

Replace the "channels": ["whatsapp", "sms"] with the V3 version "channel" : "sms"

{channelType}.from moved to top-level object

In all requests, move the from parameter inside of the channelType to the top-level object. Move the from parameter from the V2

"to": "{{toPhoneNumber}}",
"channels": ["whatsapp"],
"whatsapp": {
   "from" : "{{whatsappPhoneNumber}}",

to following V3 structure:

   "from" : "{{whatsAppBusinessNumber}}",
   "to" : "{{receiverPhoneNumber}}",
   "channel" : "whatsapp"

Harmonised Structure

The {channelType} is now renamed to content. So, change it from the following V2 structure:

“Whatsapp|sms|viber” :{
//messsage content
}

to the V3 structure:

“content” : {
//messsage content
}

Media

The V3 has a harmonized model for all channels. The media.type is now the corresponding mediatype. Replace the Whatsapp V2 structure:

 
   "media" : {
     "type" : "image",
     "url" : "https://your.image"
   },
   "contentType":"media" 

or the Viber V2 structure: 

 
 "type": "image",
 "image": {
 "url": "https://your.image"
   }

with the V3 mediatype.

 
       "contentType" : "image", //or use video|document|audio|sticker|contacts|location (contacts and location have their corresponding values)
       "image" : {
           "url": "https://your.image",
           "caption" : "An optional caption" //optional
} 

userContext

The userContext now uses a simplified model that replaces context.userContext with context. So from the V2 version:

"context": {
 "userContext": "my Context"
}

To the new V3 structure:

"context": "my Context"

Get Message

Bulk Messages

Change the {channelType} from V2: 

{
  "sms": [
    {
      "contentType": "text",
      "text": "string"
    },
    {
      "contentType": "text",
      "text": "string"
    }
  ]
}

to messages type V3 structure:

{
  "messages": [
    {
      "contentType": "text",
      "text": "string"
    },
    {
      "contentType": "text",
      "text": "string"
    }
  ]
}

Update to Webhooks:

The concept of the V2 application 

 
PATCH https://api.tyntec.com/chat-api/v2/applications/default
{
       "webhooks": [
           {
               "events": [
                   "MoMessage"
               ],
               "callbackUrl": "{{yourEndpoint}}"
           }
       ]
   }

is now replaced with the new configurations. Use this sample for replacement. 

PUT https://api.tyntec.com/conversations/v3/configurations/callbacks
{
       "callbackVersion": "2.11",
       "inboundMessageUrl": "string" //URL that receives incoming messages
       "messageStatusUrl": "string"    //  URL that receives delivery updates
   } 

Migrating: Changes specific to WhatsApp channel

Language parameter

The language code is now stored in the template object as the templateLanguage object. Change it from the previous template.language.{} in V2: 

 "template" : {
        "templateId": "{{whatsAppTemplateName}}",
        "language": {
            "policy": "deterministic",
            "code": "en"
        },

to the template.language: "string" in V3 structure. See the attached code sample:

   "template" : {
            "templateId" : "{{whatsAppTemplateName}}",
            "templateLanguage" : "{{whatsAppTemplateLanguage}}",

Components changes

The components part redesign now defines the header:[], body:[], footer:[], and buttons:[] sections. Unused arrays can be omitted. From the V2 structure with components[{type:body}]:

    "components" : [
            {"type": "body",
                "parameters": [{"type":"text", 
                                        "text" : "Peter"}]
            },
{
    "type": "header",
    "parameters": [
      {
        "type": "media",
        "media": {
          "url": "https://your.image",
          "type": "image"
        }
      }
    ]
  }
            ]    
    },

update to the V3 version components.

"components" : {
                 "header" : [
                    {
                        "type": "document", //simplified media model 
                        "document" : {
                            "url": " "https://your.document","
                        }                        
                    }
                ],   
                "body" : [ //body 
                    {
                        "type": "text",
                        "text": "User"
                    }
                ],
                 "button" : [
                    {
                        "type" : "url",
                        "index": 1,
                        "text" : "test"
                    }
                ]
]

What about V2?

The Conversations API V2 will be supported for two more years (until Apr. 15, 2023) to give you enough time for seamless migration. The breaking changes should be a cinch to change, but if you need any help, please feel free to reach out directly from your tyntec account. Although there's no immediate urgency, we encourage you to perform the migration at your earliest convenience to take full advantage of the new features!