SFTP Sync (Conversations)

James Mayr
  • Updated
Follow

Overview

This feature allows institutions to connect their Mainstay data to a third-party platform, such as an external SFTP server. This enables an outbound conversations (messages) data, including the actual incoming and outgoing messages, metadata about those messages, and information about the learner.

 

 

Setup

  1. Navigate to the Settings > SFTP Outbound page. (Note: this requires admin permissions.)
  2. Click + New Integration and select New Conversations Export.
  3. On the configuration screen, enter a Name and Description for your integration instance. This will appear in the list, but has no affect on the actual data sync. Note that you can enable or disable the integration at any time using the Enabled toggle.
  4. Next, enter your SFTP server credentials.
    1. Username, Host, and Port are required.
    2. You must enter either a Password or Private Key (and optionally a Passphrase). This information is determined by your external system.
    3. Your external system may also require files to come from specific IP addresses. If this is the case, add Mainstay's IP addresses to your Allow List: 34.197.84.241 and 3.233.244.171
    4. Click Test Connection to verify you have correctly input all credentials.
  5. In the next section, optionally add a Directory for where Mainstay should send the file. You can also customize the File Prefix. (Note that all file names will have a timestamp appended to this prefix.)
  6. The Schedule is divided into 3-hour blocks. We recommend exporting contacts once a day, during off-hours (such as 12am - 3am). (Note that all times are in EST.)
  7. Use Filtering to determine which messages to send to your external system.
    • Message Channel: select at least one communication channel
    • Message Direction: select at least one direction of messages (incoming = from the learner, outgoing = from the AI agent or Live Chat agent)
    • Outgoing Message Type: select at least one kind of message
  8. Make sure to click Save at the top after configuring your integration.

 

 

Integrations List

  1. After creating an integration instance, you can see a list of all outbound SFTP syncs.
  2. Click the Enabled toggle to turn this sync on or off.
  3. Click the ... overflow menu to see available actions:
    • Edit: Return to the configuration screen to make changes.
    • Delete: Remove this integration.

 

 

Recent Runs

Each time an outbound SFTP sync runs, an entry will be added to the Recent Runs table. Note that the Conversations export will only include new messages since the last run.

 

You can filter this table by the specific Integration (name), the Started date and time, and the Status.

 

Each row includes the following information:

  • Integration: the custom name for this integration instance (see above)
  • Type: Contacts, Conversations, or EAB Notes
  • # Rows: the count of rows in the exported CSV file
  • Started: the date and time that the integration run began
  • Finished: the date and time that the integration run completed (or failed)
  • Status: Success | Running | Skipped | Fail
    • a Skipped run indicates that there were no rows to send
    • a Failed run will indicate an error reason on hover

 

 

File

The file generated by this process will include the following fields:

  • crm_id: the unique identifier of the contact in the external platform
  • admithub_id: the unique identifier of the contact in Mainstay
  • first_name: the first name of the contact on Mainstay
  • last_name: the last name of the contact on Mainstay
  • channel: the communication channel of the conversation (one of: "web" for web-chat, or "twilio" for SMS)
  • campaign_id: the unique identifier of the Mainstay campaign that this message was part of, if applicable
  • campaign_name: the human-readable display name of the Mainstay campaign that this message was part of, if applicable
  • timestamp: the date and time that the message was recorded on Mainstay (defaults to UTC)
  • incoming: the body of the message, if it was incoming (ie, generated by the contact)
  • outgoing: the body of the message, if it was outgoing (ie, generated from a campaign, a Knowledge Base answer, or a platform user via live chat)
  • outgoing source: "AI" or "Live Chat" or "Campaign Script" or "Other", or blank if the message is incoming
  • media: a list of URLs to image attachments, if any
  • script_id: the unique identifier of the Mainstay script that this message was part of, if applicable
  • script_name: the human-readable display name of the Mainstay script that this message was part of, if applicable

 

 

Troubleshooting

Here are some tips for resolving common issues with the SFTP sync.

 

SFTP Access

The first thing to make sure is that Mainstay is able to access your external system via SFTP. Use the Test button in the SFTP Server section (Setup step 4.4). If your external system has an "Allow List" for IP addresses, make sure to add Mainstay's IP addresses (Setup step 4.3).

 

Filtering

If you're not seeing the messages you expect, double-check your Filtering (Setup step 7). Use the Conversations tool and/or the Conversations Report to verify that there are actually messages that meet your criteria. Note that the Conversations export will only include new messages since the last run.

 

Data / Field Mapping

The file Mainstay sends over will include the fields indicated above. However, your external system likely doesn't need all of these fields, so you can decide which ones to save. (Different systems will call this tool something like "Data Mapping" or "Field Mapping".) If you're not seeing the data you expect, make sure you're correctly mapping it in your system and storing it where you intend.

 

 

 

 

 

 

 

 

 

Related articles

Comments

0 comments

Article is closed for comments.