Channels and URNs
When a contact reaches out to you on a new channel, a new contact will be created. Each contact will have an address for the channel they are using, called an urn. So if they are using both SMS and Telegram, you will have two contacts, one with an SMS urn (a phone number) and one with a Telegram urn (a number with an optional display name). Our goal will be merging these urns to on the same contact with the history.Let's imagine a scenario where you have an SMS subscriber that you want to bring over to Telegram. In order to accomplish our above goal of having a single contact with two urns, we will take the following approach:
Steps
Send a text to our SMS contact with a link to our Telegram botContact clicks on the link, which starts a Telegram chat session
Contact gets an SMS message saying, you are switch to Telegram asking to confirm
They confirm by typing "yes" and we add their new Telegram urn to their contact and mark it as the channel to use
Sending the invite
To send the invitation, we'll want to text them a link to our Telegram bot. You can get the like for your Telegram bot by visiting the bot inside the Telegram client and clicking share.
Our message might look something like this:
Save on messaging fees by switching to our Telegram bot. Just click here: https://t.me/PurringtonBot?start=phone@(text_slice((urn_parts(contact.urn).path), 1))
Since we want to encode our contact's current phone number in our Telegram invite, we need to pull the actual number from their urn. We can do that using the urn_parts() function that will let us access the urn path (which in this case is a phone number).
@(urn_parts(contact.urn).path)
This would return something like, +12065551212. Telegram is picky about embedding the plus character, so next we'll trim that off since we don't actually need it anyways. To do that, we'll put that inside of a text_slice function to trim off the first character.
@(text_slice((urn_parts(contact.urn).path), 1)).
Responding to the invite
On our Telegram bot's /start flow, we'll want to check what kind of start it is. They could be joining on their own, or they might be using our special invite link. So we'll want to split at the beginning of the flow and see if it starts with /start phone. If they did give us a phone number, we can then start that phone number in a flow in order to confirm things and add our new Telegram ID.
When they click the start button, they will pass something like /start phone12065551212. We can pull out just the phone number by using our friend text_slice again.
@(text_slice, input, 12))
The result of this will just be the phone number, or in our example 12065551212. Then we just use the Start Somebody Else action to add start that phone number in our confirmation flow.
Adding the new Telegram ID
In our confirmation flow, we'll want to just ask if they are sure. If they respond with yes, then we can figure out what their Telegram ID is and save it on our SMS contact.
It's important that we ask the contact with the phone number to confirm they are switching to Telegram. Without this, somebody could start the Telegram bot with an arbitrary phone number and potentially hijack a contact that doesn't belong to them if they are in your contact database. The other way around this is you could use a random code instead of the phone number to link the two accounts, but we are sticking with phone numbers in this example for simplicity. So long as we make sure to confirm things, we should be safe from bad actors.
In this case, we know that we were started by their Telegram contact, so we know the urn for that account. To reference the contact that started us, we can use @parent.contact. And since each contact has an urn, we can use @parent.contact.urn to get the Telegram ID. This will look something like telegram:1234567#norbertk. The actual ID is the number after the : and before the #. We can access that using, you guessed it, another expression.
If we pass the parent contact's urn through urn parts, we can access the path, which in the case of Telegram is the number.
@(urn_parts(parent.contact.urn).path)
We could stop there, but Telegram users can optionally have a display name denoted with the # at the end, so if we want to include that, we can get that on as well.
@(urn_parts(parent.contact.urn).display)
So altogether it looks like this crazy thing, which is really two separate expressions with our # in the middle.
@(urn_parts(parent.contact.urn).path)#@(urn_parts(parent.contact.urn).display)
And that's it!
If you have any questions on how to accomplish this, please let us know, we are happy to help.
