The ChatShipper Developer Hub

Welcome to the ChatShipper developer hub. You'll find comprehensive guides and documentation to help you start working with ChatShipper as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

8. Outbound Messaging

Create a new Contact Conversation

To create a conversation representing a consumer, provide a contact object, and set the conversation.type to contact. You must also specify a profile with at least an identifier (email or telephone), and an error will be returned if the contact exists.

Set message.role to bot for bot-to-agent communication, agent to talk to the consumer, and contact to represent a consumer message.

Request: POST /v2/conversations

{
    "organization": "aaa111111111111111111222",
    "type": "contact",
    "contact": {
        "profile": {
            "name": "John Johnson",
            "telephone": "+31646280993"
        }
    },
    "messages": [
        {
            "text": "Hey there. Click link",
            "touchpoint": "sms",
            "role": "agent"
        },
        {
            "text": "Click link",
            "role": "agent"
        },
        {
            "text": "/leave",
            "type": "command",
            "delay": 3000
        },
        {
            "text": "Hello",
            "role": "contact",
            "delay": 10000
        }
    ]
}

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 Smooch appUser, and the contact will receive the message via Twilio SMS.
    The agent (no user specified, so defaulting to the API key owner) accepts the conversation as a result of the message, so joins with participant flags 'active' and 'accepted' set. The conversation status is set to 'active'.
  • The second message will use the now active SMS channel to provide a link button to 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 on incoming contact messages. By using a short delay we make sure the messages are processed in a next processing iteration/tick, after the previous messages.
  • The fourth message simulates an inbound contact reply; this will trigger channel notifications and set the conversation status to 'queued'.

Response: 201 CREATED

{
    "organization": "aaa111111111111111111222",
    "orgPath": "aaa111111111111111111111#aaa111111111111111111222",
    "name": "Fimlebick Fastfuzz",
    "type": "contact",
    "slug": "HJIGT96F7",
    "url": "https://s-view.chatshipper.com/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",
        "5bb01d17d99faf11a3f4a375"
    ],
    "channels": [
        "5b99be371951542b5f47eeb4",
        "5b2bf9dd9f3c885eb7ad7a63"
    ],
    "channelsOffline": [
        "5b9ae5460a13a54282ca20d0",
        "5b5f96a3f4178329fae6890a",
        "5b5f96a3f4178329fae6890c",
        "5b8c8a35aabb62677b5b2332"
    ],
    "touchpoints": {
        "web": {
            "services": [],
            "selected": 0
        },
        "email": {
            "services": [],
            "selected": 0
        },
        "sms": {
            "services": [
                "5b6f8a73623a375f28a5380c"
            ],
            "selected": true
        },
        "facebook": {
            "services": [],
            "selected": 0
        }
    },
    "forms": [],
    "results": [],
    "createdBy": "aaa000000000000000000111",
    "updatedAt": "2018-09-30T00:47:20.122Z",
    "createdAt": "2018-09-30T00:47:09.787Z",
    "id": "5bb01d0dd99faf11a3f4a36c"
}

Channel (SMS or Email to Web) Transfer

Request: POST /v2/conversations

{
    "organization": "aaa111111111111111111222",
    "type": "contact",
    "contact": {
        "profile": {
            "name": "John Johnson",
            "telephone": "+31646280993"
        }
    },
    "messages": [
        {
            "role": "agent",
            "text": "Hey there. Time for a new appointment.",
            "touchpoint": "sms",
        },
        {
            "role": "agent",
            "text": "Click the link to continue:",
            "touchpoint": "sms",
            "delay": 5000,
            "actions": [{
                "text": "[continue conversation]",
                "type": "link",
                "uri": "http://yoursite.com/widget?id={authuser}&token={authtoken}"
            }]
        }
    ]
}

For more details, see the API Reference.

8. Outbound Messaging


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.