Business Initiated Conversations
Usually, in Web1on1, conversations are initiated by the end-user (the consumer, called "contact"). Whether they are sending an email to your support address, reaching out on Facebook Messenger, or contacting you via WhatsApp, the typical flow requires the contact to message first. However, in some circumstances it is necessary for the business to proactively reach out to a new contact and engage them in a conversation.
Each contact is linked to exactly one conversation. When creating a new conversation through the API, a contact record is also created for the provided contact.profile. In addition, at least one outbound message must be provided, which will be sent to the contact immediately.
Creating Contact Conversations
To create a conversation representing a consumer, provide an organization ID, a contact object containing profile identifiers, and set the conversation type to contact. You must supply the contact.profile with at least one identifier (email and/or telephone, preferably both). Also, specify an array of messages with at least one entry.
Set message.role to:
- bot for bot-to-agent communication,
- agent to talk to the consumer, and
- contact to represent a consumer message.
Bots talking to consumers would do so with message.role "agent".
Here's a simple example, sending an email:
Request: POST https://api.web1on1.chat/v2/conversations
{
"organization": "6663a1f684ba342816c4b7c4",
"type": "contact",
"contact": {
"profile": {
"name": "John Johnson",
"email": "johnjohn@example.com"
}
},
"messages": [
{
"text": "Hey there!",
"touchpoint": "email",
"role": "agent"
}
]
}If none the contact identifiers match an existing contact, the conversation will be created, and a 201 Created http status response will be returned. If the contact already exists, the request is processed as an Upsert (Insert or Update): the messages will be added to the existing conversation, and a 200 OK http response returned.
Conversations "Upsert" (Insert or Update)
Since the POST /v2/conversations endpoint operates as an Upsert, it provides a simple way to add one or more messages to an existing conversation. Specifying an organization and contact identifiers are no longer needed in that case. Example:
Request: POST https://api.web1on1.chat/v2/conversations
{
"id": "66c3ed372a33131f1b4ba1b8",
"messages": [
{
"text": "Hey there!",
"touchpoint": "email",
"role": "agent"
}
]
}The results are identical to POSTing the message array to the conversation's messaging endpoint:
Request: POST https://api.web1on1.chat/v2/conversations/66c3ed372a33131f1b4ba1b8/messages
Example: Create a new SMS conversation
Request: POST https://api.web1on1.chat/v2/conversations
{
"organization": "aaa111111111111111111222",
"type": "contact",
"contact": {
"profile": {
"name": "John Johnson",
"telephone": "+31646280994"
}
},
"messages": [
{
"text": "Hey there.",
"touchpoint": "sms",
"role": "agent"
},
{
"text": "How are you?",
"role": "agent"
},
{
"text": "/leave",
"type": "command",
"delay": 3000
}
]
}This creates the contact record, and processes the messages:
- The first message needs to provide a touchpoint, as a conversation.touchpoint is not specified. It will link the contact through a Sunshine Conversations appUser, and the contact will receive the message via Twilio SMS. The agent (no message.user specified, so defaulting to the API key owner) accepts the conversation as a result of the message, so will automatically join the conversation with participant flags 'active' set. The conversation status is set to 'active'.
- The second message will use the now active SMS channel to send a second message the contact. These first two messages were sent as an SMS to John's mobile phone.
- The third message makes the bot leave the conversation; this will close the conversation and trigger channel notifications when new contact messages come in. By using a short delay we make sure the messages are processed in a next processing iteration/tick, after the previous messages.
Response: 201 CREATED
{
"organization": "aaa111111111111111111222",
"orgPath": "aaa111111111111111111111#aaa111111111111111111222",
"name": "Fimlebick Fastfuzz",
"type": "contact",
"slug": "HJIGT96F7",
"url": "https://app.web1on1.chat/c/HJIGT96F7",
"status": "queued",
"contact": "5bb01d0dd99faf11a3f4a36d",
"participants": [
{
"updatedAt": "2018-09-30T00:47:19.872Z",
"createdAt": "2018-09-30T00:47:09.868Z",
"name": "testbot",
"avatar": "https://storage.googleapis.com/cs2-uploads/avatars/ca6e1762-988e-4cbc-becb-ad952b6df9a4.png",
"user": "aaa000000000000000000111",
"unreadCount": 1,
"inbox": false,
"accepted": false,
"active": false,
"role": "agent"
}
],
"messages": [
"5bb01d0dd99faf11a3f4a36e",
"5bb01d0dd99faf11a3f4a36f",
"5bb01d0fd99faf11a3f4a374"
],
"channels": [
"5b99be371951542b5f47eeb4"
],
"channelsOffline": [
"5b9ae5460a13a54282ca20d0"
],
"touchpoints": {
"sms": {
"services": [
"5b6f8a73623a375f28a5380c"
],
"selected": true
}
},
"forms": [],
"results": [],
"createdBy": "aaa000000000000000000111",
"updatedAt": "2018-09-30T00:47:20.122Z",
"createdAt": "2018-09-30T00:47:09.787Z",
"id": "5bb01d0dd99faf11a3f4a36c"
}Example: create a new WhatsApp conversation
If you know for a fact that the new contact has a WhatsApp account tied to his/her telephone number, it's possible to start the conversation with the customer over WhatsApp. The initial message (and any message therafter, until the contact replies) must be an approved WhatsApp Template message.
Request: POST https://api.web1on1.chat/v2/conversations
{ "organization": "5bad2f12e91d2c331be33364", "type": "contact", "contact": { "profile": { "name": "John Johnson", "telephone": "+31646280994" } }, "messages": [{ "role": "agent", "text": "Your car is ready to be picked up!", "touchpoint": "whatsapp", "meta": { "template": "your_car_is_ready", "language": "nl" } }] }
- The
message.textwill be replaced by the template text before it's sent to the consumer. - Specifying
message.meta.languageis optional, and defaults to the conversation or organization language.