Conversation Lifecycle

Creating a conversation

An Inbox App conversation is created in Follow Up Boss when you send a message to the Create Message API endpoint with a new externalConversationId. The External Conversation ID is a unique ID generated by you per-conversation and used to link messages together within the same conversation.

Choosing the right inbox

📘

Ownership can only be set for new conversations.

Once a conversation is created it's ownership can not be changed and any subsequent messages including an owner object will be rejected.

Depending on the scope of your Inbox App installation, conversations can be added to a specific user's inbox (in the case of a user scoped installation) or to any user or Team Inbox (in the case of an account scoped installation.) Once a conversation is created in an inbox, only assignment of that conversation can be changed - not ownership.

You will specify the owning inbox of the conversation using the owner object when sending the first message in a new conversation. You can use GET /users and GET /teamInboxes to determine available user and Team Inboxes to create conversations in.

Specifying the person (lead)

When you create a new conversation you are required to specify the person on the other end of the conversation. If known, this can be a FUB Person ID. If unknown, this can be any combination of name, email, or phone.

If a Person ID is not provided, we will always attempt to match the provided information to a known lead in FUB so it is considered best practice to provide as much information as possible.

Updating the person

📘

Persons matched to a lead in Follow Up Boss become immutable.

Once a person has been matched to a lead in Follow Up Boss, it becomes immutable and any subsequent updates including the person object will be rejected.

If your application learns more information about a person - for example if you started the conversation only knowing their email and later learned their name, you can update the conversation with a new person object.

Adding the message

The new conversation is started by adding a message with a new externalConversationId. Below is a minimal new message example, see the add message documentation for a full list of available fields.

{
  "externalConversationId": "",
  "externalMessageId": "",
  "message": "An example message.",
  "isIncoming": true,
  "sender": {
    "personId": 123,
  },
  "person": {
    "id": 123,
  },
  "owner": {
    "userId": 1
  }
}

Updating a message

Outgoing messages (messages with a false isIncoming value) can be updated with a delivery status and, in the case of delivery failures, an error message. See the Delivery Status guide for more information.

Updating a conversation

Conversations can be updated using the Update Conversation API endpoint to perform the following actions:

• Change the subject of the conversation.
• Archiving or unarchiving the conversation.
• Assigning or un-assigning the conversation.
• Updating the associated person (until a valid Person ID is associated, after which is becomes immutable.)

Receiving replies from Follow Up Boss

Users can reply to Inbox App conversations directly from Follow Up Boss. When this happens, we'll send an inboxAppReply webhook to your Subscription URL. See the Webhooks guide for more information.