Business Initiated Conversations

Usually in Smooch, conversations are initiated by the end-user. Whether they are sending an email to your support address, reaching out on Facebook Messenger, or contacting you via one of our Embeddable SDKs, the typical flow requires the user to message first. However, in some circumstances it is necessary for the business to proactively reach out to the user and engage them in a conversation.

Smooch supports a number of methods of initiating a conversation with a user, depending on what information you have about the user, and which channel you would like to initiate the conversation on. The purpose of this section is to describe how these methods work, and explain how they can be used.

Smooch Embeddable SDKs

To initiate a conversation with a user on your mobile app or website, you first need to ensure that the conversation exists. By default, the SDKs will delay creation of the user and conversation until the latest possible moment, typically when the user is about to send their first message. In order to proactively reach out to a user, your application or website must signal your intent to do so via the startConversation method on iOS, Android, or Web. This method tells the SDK that you intend to message the user, which will trigger a user and conversation creation in Smooch. Once the conversation is started, you can send a message to that user like any other.

Example flow on Web Messenger

  1. A user navigates to your online store in their browser. They do not have a registered account with your website, and the user is browsing anonymously.
  2. When the page loads, you call the init method to initialize the Web Messenger and display the call to action in the bottom right hand corner of the screen, in case the user needs to reach out for support. The SDK is now initialized in anonymous mode, but the user and conversation record do not yet exist.
  3. The user doesn’t need any help, and instead completes a transaction anonymously. This is an important event in your user flow, and you determine that now is the correct time to reach out to the user.
  4. Your website calls the startConversation method to signal to Smooch that you would like to reach out to the user.
  5. The SDK creates a user and conversation, and signals your server with a conversation:start webhook event. The SDK opens a websocket connection to receive business messages.
  6. Your server retrieves the user’s ID from the webhook payload, and sends a message via the Post Message API.
  7. The message is received by the browser, and displays an unread indicator over the messaging button.
  8. The user clicks the button and is able to view the message, and reply if necessary.

Example flow on iOS

  1. A user downloads your application from the App Store, and is promted to create an account before they can continue.
  2. When the application launches, you call +initWithSettings:completionHandler: to initialize the SDK.
  3. When the user completes the sign up flow, your application creates an account with your own server, and is returned a JWT for the newly created user.
  4. Your application calls +login:jwt:completionHandler: to identify the user on the SDK and provide the JWT generated in the previous step. The user is now authenticated in Smooch, but the user and conversation record do not yet exist.
  5. During your sign up flow, or at some other point that you have deemed appropriate, your application requests user notification permission in order to send push notifications to the user. (This step is required if you intend to reach out to the user after they have already closed your application).
  6. The user makes a purchase in your application, and opts in to receive status updates on their order. This is an important event in your user flow, and you determine that now is the correct time to create the user.
  7. Your application calls the +startConversationWithCompletionHandler: method to signal to Smooch that you would like to reach out to the user at some point in the future.
  8. The SDK creates a user and conversation, and signals your server with a conversation:start webhook event. The push notification token obtained in step 5 is automatically associated to the user and stored alongside their profile information.
  9. Your server retrieves the user’s userId from the webhook payload, and matches it with the userId provided at login time in step 4.
  10. At a later time, the status of the user’s order is updated, and your system decides that the user should be notified.
  11. Your server sends a message via the Post Message API, using the userId that was assigned in step 4.
  12. The user receives a push notification with the contents of your message, and can tap it to open the conversation screen to view the message history, and reply if necessary.

SMS

If your business has a phone number for a user, reaching out to the user via SMS is simple. First, use the Pre-Create App User endpoint to create a user in Smooch to associate the phone number with:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers \
     -X POST \
     -d '{"userId": "3w7AQigJkJDkfnnKW5fF1I", "credentialRequired": true}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

When using this API, you need to assign them a userId, which typically maps to some other identifier in your system. Then, use the Link App User To Channel endpoint to associate the created user to a phone number, and send the first message:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/3w7AQigJkJDkfnnKW5fF1I/channels \
     -X POST \
     -d '{"type": "twilio", "confirmation": {"type": "immediate", "message": { "role": "appMaker", "type": "text", "text": "Hello there" }}, "phoneNumber": "+15555555555"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

The user should receive a text message and be able to reply right away.

Email

If your business has an email address for a user, reaching out to the user via email is simple. First, use the Pre-Create App User endpoint to create a user in Smooch to associate the email address with:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers \
     -X POST \
     -d '{"userId": "3w7AQigJkJDkfnnKW5fF1I", "credentialRequired": true}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

When using this API, you need to assign them a userId, which typically maps to some other identifier in your system. Then, use the Link App User To Channel endpoint to associate the created user to an email address, and send the first message:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/3w7AQigJkJDkfnnKW5fF1I/channels \
     -X POST \
     -d '{"type": "mailgun", "confirmation": {"type": "immediate", "message": { "role": "appMaker", "type": "text", "text": "Hello there" }}, "address": "steveb@channel5.com"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

The user should receive an email message and be able to reply right away.

Facebook Messenger

If your business has a phone number for a user, you can use customer matching to reach out to users over Facebook Messenger.

First, use the Pre-Create App User endpoint to create a user in Smooch to associate the phone number with:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers \
     -X POST \
     -d '{"userId": "3w7AQigJkJDkfnnKW5fF1I", "credentialRequired": true}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

When using this API, you need to assign them a userId, which typically maps to some other identifier in your system. Then, use the Link App User To Channel endpoint to perform a customer matching request using the phone number (and optionally a name):

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/3w7AQigJkJDkfnnKW5fF1I/channels \
     -X POST \
     -d '{"type": "messenger", "confirmation": {"type": "userActivity", "message": { "role": "appMaker", "type": "text", "text": "Hello there" }}, "phoneNumber": "+15555555555", "givenName": "Steve", "surname": "Brule"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

If the match was successful, the user will receive a message request in Messenger, and can choose to accept or decline the request. If the user accepts, they are able to start messaging right away.