How to recognise a conversation type (web, email, whatsapp) in ChatShipper?

Updated 3 weeks ago by Joost Rijlaarsdam

TLDR

A conversation has no type, its messages have a ´touchpoint´

Question:

I use the API to Retrieve a Conversation /conversations/{conversation_id} to get conversations and now we have an issue to recognise type/source for this conversation (web, email etc). I didn't find this information in a conversation body. I decide it can be "touchpoints" but for example for this conversation 5f50efdxxxxxxxxxxxxx we have two touchpoints: video and web which is weird for me, so I not sure it's right field.

Answer:

A conversation does not have a "type" like this - any contact conversation can use any service integration over the course of its lifetime.The conversation.touchpoints represents the service integrations available to the conversation; they correspond to the touchpoint tabs beneath the message input in the UI.

Activated touchpoints will have one or more services specified. https://api.chatshipper.com/#messaging-conversations

Consider an organization with the web widget and email integrations enabled. When a new web conversation comes in, the conversation touchpoints will look somewhat like this:

"touchpoints": { 
"web": {
"services": ["5dd72ac0xxxxxxxxxxxx"],
"selected": true
},
"email": {
"services":[],
"selected": false
}
}

Adding an email address to the contact profile (in the UI) will enable outbound emailing: an "Email" tab is now added to the conversation in the UI, and the email service is enabled as a conversation touchpoint:

"touchpoints": { 
"web": {
"services": ["5dd72ac0xxxxxxxxxxxx"],
"selected": true
},
"email": {
"services": ["5f53a2c12dxxxxxxxxxx"],
"selected": false
}
}

Note that no actual emails have been sent yet at this point - the existence of a non-empty touchpoint.email.services only tells you that it's possible to send emails from this conversation, because:

  1. The org has the email integration (Mailgun) enabled;
  2. There's an email address filled in for this contact

conversation.touchpoints doesn't say much about what actually took place - for that, listen to messages as they happen (event-based) or take a look at the contact:

Each contact conversation (conversation.type: 'contact') has a corresponding contact record. You'll find the contact ID as conversation.contact, and use the contacts API to fetch it:

GET /v2/contacts/{contact_id}

You can also populate the contact record when fetching the contact's conversation:

GET /v2/conversations/{conversation_id}?populate=contactcontact.presences

Once communication has progressed over a consumer channel, the consumer endpoint (what we call contact presence) is recorded in the contact record. In the example earlier, no email was exchanged yet, so the contact only has a presence for the 'web' touchpoint:

Note in the screenshot above, I'm querying a conversation and providing ?populate=contact. I could have also fetched the contact directly (GET /v2/contacts/:id).https://developers.chatshipper.com/developers/apireference/fetchingresources/#field-population

Because an email integration is available (in the example earlier), the contact could send an email. Or the agent could send an email to the contact. When either of that happens,

  1. A message is added to the conversation with message.touchpoint: "email"
  2. The email connection with the contact is recorded as a new contact.presences having platform "email". If you fetch the contact record again, you should see the "email" presence listed in the contact.presences. The contact should now also surface when querying for contacts that have an email connection (presence) established (by having sent/received an email):
    GET /v2/contacts?presences.platform=email

event: message.create (message.touchpoint)

All of the above is useful for one-off / batch processes, but as your integrations mature, you'll want to respond to events as they happen, for example every time an email is sent/received (message.touchpoint: "email").

events: contact.create, contact.update

Again, to keep track of things as they happen (eg an email connection being established), you could listen to contact change events and inspect contact.presences for anything interesting.

This is the gist of it, in general. The approach to take depends on the goal you're trying to accomplish and to what purpose - that wasn't clear from the question (why you want to "recognise type/source for this conversation").

Hope this helps.


How did we do?