Create conversation

Ω While configuring flows in Webex Connect, you will need to use this node to create a conversation with the customer's channel identity and the business's channel asset. Some channels may require additional context to resolve a message for e.g. subject in email conversations. This node calls Webex Engage's 'Search conversation' API to check for existing conversations on Webex Engage. A detailed guide has been listed in the table below:

Channel	Customer Address (customerAddress)	Business Address (bizAddress)	Additional context
SMS	Customer Mobile Number	Business Longcode
Facebook Messenger	Page Scoped ID	Page ID
Livechat	User ID	App ID	Thread ID, User ID and Browserfingerprint
Email	Email ID	Business Mailbox	Subject, To Recipients, Cc Recipients, In Reply To Header
Apple Messages for Business	AMB User ID	AMB Account ID
WhatsApp Business	WhatsApp Mobile Number	WhatsApp Business Longcode
API	User ID	Business ID	Business ID can be fetched from New Admin console.

Node screenshot - Create conversation

Create conversation

How to configure this node

• Drag the node from the 'Node Palette' on the left by searching against the name 'Create conversation'
• Double-click to open the node
• Select the Method Name - Create conversation
• Select your configured Authorization in the Node Authentication field. It is recommended that you set this to a Default Authentication that has been configured in WxEngage's Integrations screen under WxConnect's Integrations as all your nodes across flows will pick up the updated token once you re-authenticate from the Integrations screen.
• Configure the remaining fields based on the table below:

 SMS

• Channel - SMS
  Set channel to SMS
• Conversation Alias ID
  Unique Auxiliary reference identifier that you would like to associate to the Conversation ID
• Business Longcode / Shortcode
  Choose your Business Longcode / Shortcode from the list of Assets shown in the dropdown
• Customer Mobile Number - Generally set to$(n2.sms.msisdn)
  MSISDN from the output variables of the start node is the customer mobile number
• Customer Name - null or Generally set to a value fetched from external services
  To be fetched from external services (if any), else set to null
• Messages
  Set to one of the following options:
  • None: Creates a blank conversation without any messages
  • Single Message: Configure all associated values in the UI
  • Dynamic Multi-message(s) JSON array: Pass a variable containing a JSON array. Refer SMS schema here
• Message Alias ID - Generally set to $(n2.messenger.transId)
  Unique auxiliary external reference identifier to maps to the message.
• Direction - Inbound or Outbound or Announcement
  Direction of the message
• Message Type - Text SMS supports message type: text alone.
• Text - $(n2.sms.message)
message from the output variables of the start node is the Text
• Timestamp (ISO8601 Format in UTC Timezone) - $(n2.sms.ts)
tsin the output variables of the start node which contains the SMS Timestamp
• Custom Fields (Optional)
  • Scope: Choose the scope of the field. Can be set to Conversation or Profile(mapped to the customer's 360 degree profile)
  • Key: Key of the field
  • Value: Value of the field

Facebook Messenger

• Channel - Facebook Messenger
  Set channel to Facebook Messenger
• Conversation Alias ID
  Unique Auxiliary reference identifier that you would like to associate to the Conversation ID
• Page ID
  Choose your Facebook Messenger Page from the list of Assets shown in the dropdown
• Page Scoped ID (PSID) - $(n2.messenger.psId)
  PSID from the output variables of the start node is the Facebook PS ID
• Customer Name - $(n2.messenger.name)
name from the output variables of the start node is the Customer Name
• Messages
  Set to one of the following options:
  • None: Creates a blank conversation without any messages
  • Single Message: Configure all associated values in the UI
  • Dynamic Multi-message(s) JSON array: Pass a variable containing a JSON array. Refer FBM schema here
• Message Alias ID - Generally set to $(n2.messenger.transId)
  Unique auxiliary external reference identifier to maps to the message.
• Direction - Inbound or Outbound or Announcement
  Direction of the message
• Message Type - Text (or) Text with attachments
  Recommended to set to Text with attachments
• Text - $(n2.messenger.message)
message from the output variables of the start node is the Text
• Attachments - $(parseDataAttachment)
  This is one of the Evaluate node variables which contains the processed inbound attachment array object.
• Timestamp (IN UTC) - $(n2.messenger.ts)
ts in the output variables of the start node which contains the Messenger Timestamp
• Custom Fields (Optional)
  • Scope: Choose the scope of the field. Can be set to Conversation or Profile(mapped to the customer's 360 degree profile)
  • Key: Key of the field
  • Value: Value of the field

Livechat

• Channel - Livechat
  Set channel to Livechat
• Conversation Alias ID
  Unique Auxiliary reference identifier that you would like to associate to the Conversation ID
• Livechat App
  Choose your Livechat App from the list of Assets shown in the dropdown
• Livechat Website Domain - Stored under custom variables
  Website domain in which the Live Chat widget is embedded. The website domain is available in the app settings page.
• Livechat Thread ID - Generally set to$(n2.inappmessaging.threadId)
threadId from the output variables of the start node is the Thread ID**
• Livechat User ID - Generally set to$(n2.inappmessaging.userId)
userId from the output variables of the start node is the Livechat User ID
• Livechat Browser Fingerprint - Generally set to$(n2.inappmessaging.userId)
userId from the output variables of the start node is the Livechat Browser Fingerprint
• Customer Name -
  Fetched from Receive node's Form Response (that accepts Name as one of the Form Fields) or an external system
• Messages
  Set to one of the following options:
  • None: Creates a blank conversation without any messages
  • Single Message: Configure all associated values in the UI
  • Dynamic Multi-message(s) JSON array: Pass a variable containing a JSON array. Refer Livechat schema here
• Message Alias ID - Generally set to $(n2.inappmessaging.transId)
  Unique auxiliary external reference identifier to maps to the message.
• Direction - Inbound or Outbound or Announcement
  Direction of the message
• Message type:
  • Livechat Text with attachments
    • Text - Generally set to$(n2.inappmessaging.message)
message from the output variables of the start node is the Text
    • Attachments - Generally set to$(parseDataAttachment) in templated flows
      This is one of the Evaluate node variables which contains the processed inbound attachment array object.
  • Livechat Text with carousel
    • Text - $(n2.inappmessaging.message)
message from the output variables of the Start node is the Text
    • Livechat Carousel Object - JSON or Flow variable
      Pick up from the Send node output variables
  • Livechat Text with quick replies
    • Text - $(n2.inappmessaging.message)
message from the output variables of the Start node is the Text
    • Quick Replies Object - JSON or Flow variable
      Pick up from the Send node output variables
  • Form Response
    • Livechat Form Response - JSON or Flow variable
      Pick up from the Receive node output variables
  • Livechat Carousel Response
    • Livechat Carousel Response - JSON or Flow variable
      Pick up from the Receive node output variables
  • Livechat Quick replies response
    • Livechat Quick Replies Response - JSON or Flow variable
      Pick up from the Receive node output variables
• Timestamp (IN UTC) - $(n2.messenger.ts)
tsin the output variables of the start node which contains the Messenger Timestamp
• Custom Fields (Optional)
  • Scope: Choose the scope of the field. Can be set to Conversation or Profile(mapped to the customer's 360 degree profile)
  • Key: Key of the field
  • Value: Value of the field

Email

• Channel - Email
  Set channel to Email
• Conversation Alias ID
  Unique Auxiliary reference identifier that you would like to associate to the Conversation ID
• Business Email ID
  Choose your Business Mailbox from the list of Assets shown in the dropdown
• Subject - Generally set to$(n2.email.subject)
subject in the output variables of the start node is the subject
• Customer Email ID - Generally set to $(n2.email.emailId)
emailId in the output variables of the start node is Customer Email ID
• Customer Name - Generally set to$(n2.email.senderName)
  Name of the customer who sent the inbound email. May not be received all the time, subject to the email servers capabilities.
• Messages
  Set to one of the following options:
  • None: Creates a blank conversation without any messages
  • Single Message: Configure all associated values in the UI
  • Dynamic Multi-message(s) JSON array: Pass a variable containing a JSON array. Refer Email schema here
• Message Alias ID - Generally set to $(n2.email.transId)
  Unique auxiliary external reference identifier to maps to the message.
• Direction - Inbound or Outbound or Announcement
  Direction of the message
• Message type: - Set to Email
  Type of message
• From address - Generally set to$(n2.email.emailId)
emailId in the output variables of the start node is the From Address
• To address - Generally set to$(n2.email.toAddresses)
toAddresses in the output variables of the start node is the To Address
• CC recipients - Generally set to$(n2.email.ccRecipients)
ccRecipients in the output variables of the start node is the CC recipients
• Email headers - Generally set to $(n2.email.headers)
  Email headers key-value pairs object obtained from the start node output variables
• HTML email body - Generally set to$(n2.messenger.htmlBody)
htmlBody in the output variables of the start node is the HTML email body
• Plain email body - Generally set to$(n2.email.strippedText)
strippedText in the output variables of the start node is the HTML email body
• Stripped HTML - Generally set to$(n2.email.strippedHtml)
strippedHtml in the output variables of the start node is the Stripped HTML
• Stripped text - Generally set to$(n2.email.strippedText)
strippedText in the output variables of the start node is the Stripped Text
• Attachments - $(parseDataAttachment)
  This is one of the Evaluate node variables which contains the processed incoming attachment array object from customer respectively
• Timestamp (IN UTC) - $(n2.messenger.ts)
ts in the output variables of the start node which contains the Messenger Timestamp
• Custom Fields (Optional)
  • Scope: Choose the scope of the field. Can be set to Conversation or Profile(mapped to the customer's 360 degree profile)
  • Key: Key of the field
  • Value: Value of the field

Apple Messages for Business

• Channel - Apple Messages for Business
  Set channel to Apple Messages for Business
• Conversation Alias ID
  Unique Auxiliary reference identifier that you would like to associate to the Conversation ID
• AMB Account ID
  Choose your AMB Account ID from the list of Assets shown in the dropdown
• AMB User ID - Generally set to$(n2.abc.abcUserId)
abc.abcUserId in the output variables of the start node is the AMB User ID
• Customer Name - Generally set to a custom variable - $(customerName)
  AMB does not provide Customer Name by default. You can set this to a variable that points to a value obtained from external integrations such as CRMs, etc.
• Messages
  Set to one of the following options:
  • None: Creates a blank conversation without any messages
  • Single Message: Configure all associated values in the UI
  • Dynamic Multi-message(s) JSON array: Pass a variable containing a JSON array. Refer AMB schema here
• Message Alias ID - Generally set to $(n2.abc.transId)
  Unique auxiliary external reference identifier to maps to the message.
• Direction - Inbound or Outbound or Announcement
  Direction of the message
• Message type:
  Type of message
  • Text with attachments
    • Text - Generally set to$(n2.abc.message)
message from the output variables of the start node is the Text
    • Attachments - Generally set to$(parseDataAttachment) in templated flows
      This is one of the Evaluate node variables which contains the processed inbound attachment array object.
  • AMB List picker response
    • AMB List picker response - JSON or Flow variable
      Pick up from the Receive node output variables
  • AMB Time picker response
    • AMB Time picker response - JSON or Flow variable
      Pick up from the Receive node output variables
  • AMB Form response
    • AMB Form response - JSON or Flow variable
      Pick up from the Receive node output variables
  • AMB Quick replies response
    • AMB Quick replies response - JSON or Flow variable
      Pick up from the Receive node output variables
  • AMB List picker
    • AMB List picker - Generally set to $(n30.send.listPicker)
      Pick up from the Output variables of an AMB send node
  • AMB Time picker
    • AMB Time picker - Generally set to $(n30.send.timePicker)
      Pick up from the Output variables of an AMB send node
  • AMB Form
    • AMB Form - Generally set to $(n30.send.response_interactive)
      Pick up from the Output variables of an AMB send nodeAMB Quick replies
  • AMB Quick replies
    • AMB Quick replies - Generally set to $(n30.send.quickReplies)
      Pick up from the Receive node output variables
• Timestamp (IN UTC) - Generally set to$(n2.abc.ts)
ts in the output variables of the start node which contains the Timestamp
• AMB Capability List - Generally set to $(n2.abc.capabilityList)
  Determines the supported message types that the customer's device supports

WhatsApp Business

• Channel - WhatsApp
  Set channel to WhatsApp
• Conversation Alias ID
  Unique Auxiliary reference identifier that you would like to associate to the Conversation ID
• WhatsApp Longcode
  Choose your WhatsApp Longcode from the list of Assets shown in the dropdown
• WhatsApp Mobile Number - Generally set to$(n2.whatsapp.waId)
waId in the output variables of the start node is the subject
• Customer Name - $(n2.whatsapp.username)
name from the output variables of the start node is the Customer Name
• Messages
  Set to one of the following options:
  • None: Creates a blank conversation without any messages
  • Single Message: Configure all associated values in the UI
  • Dynamic Multi-message(s) JSON array: Pass a variable containing a JSON array. Refer WAB schema here
• Message Alias ID - Generally set to $(n2.whatsapp.transId)
  Unique auxiliary external reference identifier to maps to the message.
• Direction - Inbound or Outbound or Announcement
  Direction of the message
• Message Type
  Type of message
  • Text with attachments
    • Text - $(n2.whatsapp.message)
message from the output variables of the start node is the Text
    • Attachments - $(parseDataAttachment)
      This is one of the Evaluate node variables which contains the processed incoming attachment array object from the customer respectively
  • WhatsApp List
    • WhatsApp List - Generally set to $(n30.send.response_interactive)
response_interactive from the output variables of the Send node is WhatsApp List
  • WhatsApp Buttons
    • WhatsApp Buttons - Generally set to $(n2.send.response_interactive)
response_interactive from the output variables of the Send node is WhatsApp Buttons
  • WhatsApp Interactive Response
    • WhatsApp Interactive Response - JSON or variable
      Construct a JSON as per the payload mentioned in the WAB schema page
• Timestamp (IN UTC) - $(n2.whatsapp.ts)
ts in the output variables of the start node which contains the WhatsApp Timestamp

API

• Channel - API
  Set channel to API
• Conversation Alias ID
  Unique Auxiliary reference identifier that you would like to associate to the Conversation ID
• Business ID
  Choose your Business ID from the list of Assets shown in the dropdown
• User ID - Custom variable
  Unique identifier of the customer as per the channel in context
• Customer Name - $(n2.whatsapp.username)
name from the output variables of the start node is the Customer Name
• Messages
  Set to one of the following options:
  • None: Creates a blank conversation without any messages
  • Single Message: Configure all associated values in the UI
  • Dynamic Multi-message(s) JSON array: Pass a variable containing a JSON array. Refer API message schema here
• Message Alias ID - Generally set to $(n2.whatsapp.transId)
  Unique auxiliary external reference identifier to maps to the message.
• Direction - Inbound or Outbound or Announcement
  Direction of the message
• Message Type
  Type of message
  • Text with attachments
    • Text - $(n2.whatsapp.message)
message from the output variables of the start node is the Text
    • Attachments - $(parseDataAttachment)
      This is one of the Evaluate node variables which contains the processed incoming attachment array object from the customer respectively
• Timestamp (IN UTC) - Custom Timestamp Variable
  ISO8601 format of the timestamp

Output variables

Variable	Description
transId	API request identifier generated by WxEngage

📘

Note

Although the output variables do NOT surface the conversation ID created, you can utilise this value downstream in the flow using the variable $(conversationId)

Node outcomes

Category	Outcome	Description
Success	onConversationCreated	Conversation created successfully
Errors	onConversationFailed	WxEngage failed to create a conversation
	onTimeout	Could not receive an API response from WxEngage within the agreed time-out
	onInvalidData	Invalid data configured in WxConnect node
	onError	Error in WxConnect's middleware services
	onInvalidChoice	Invalid choice
	onauthorizationfail	Failed to Authorize successfully. Recommend to recheck Auth details in the Authorize Integration section
	Failure	Any other run time failures