Transmitting Data to SFTP

SFTP is the supported mechanism for one-time data transmissions, typically used for sending training data files during the implementation phase prior to initial launch. ASAPP customers can transmit the following types of training data via SFTP:

• Conversation transcripts from messaging or voice interactions
• Recorded call audio files
• Free-text agent notes associated with messaging or voice interactions

Getting Started

ASAPP will require you to provide the following information to set up the SFTP site.

• An SSH public key.  This should use RSA encryption with a key length of 4096 bits.

ASAPP will provide you a username to associate with the key. This will be of the form: sftp<company marker> where the company marker will be selected by ASAPP.  For example a username could be: sftptestcompany

In your network, open port 22 outbound to sftp.us-east-1.asapp.com.

Data File Formatting and Preparation

General Requirements:

• Files should be UTF-8 encoded.
• Control characters should be escaped.
• You may provide files as CSV or JSONL format, but we strongly recommend JSONL where possible. (CSV files are just too fragile.)
• If you send a CSV file, ASAPP recommends that you include a header. Otherwise, your CSV must provide columns in the exact order listed below.
• When providing a CSV file, you must provide an explicit null value (as the unquoted string: NULL ) for missing or empty values.

Call Center Data File Structure

The table below shows the required fields to include in your uploaded call center data.

FIELD NAME	REQUIRED?	FORMAT	EXAMPLE	NOTES
customer_id	Yes	String	347bdddb-d3a1-45fc-bbcd-dbd3a175fc1c	External User ID. This is a hashed version of the client ID.
conversation_id	No	String	21352352	If filled in, should map to ASAPP’s system.  May be empty, if the customer has not had a conversation with ASAPP.
call_start	Yes	Timestamp	2020-01-03T20:02:13Z	ISO 8601 formatted UTC timestamp.  Time/date call is received by the system.
call_end	Yes	Timestamp	2020-01-03T20:02:13Z	ISO 8601 formatted UTC timestamp.  Time/date call ends. Note: duration of call should be Call End - Call Start.
call_assigned_to_agent	No	Timestamp	2020-01-03T20:02:13Z	ISO 8601 formatted UTC timestamp. The date/time the call was answered by the agent.
customer_type	No	String	Wireless Premier	Customer account classification by client.
survey_offered	No	Bool	true/false	Whether a survey was offered or not.
survey_taken	No	Bool	true/false	When a survey was offered, whether it was completed or not.
survey_answer	No	String		Survey answer
toll_free_number	No	String	888-929-1467	Client phone number (toll free number) used to call in that allows for tracking different numbers, particularly ones referred directly by SRS. If websource or click to call, the web campaign is passed instead of TFN.
ivr_intent	No	String	Power Outage	Phone pathing logic for routing to the appropriate agent group or providing self-service resolution. Could be multiple values.
ivr_resolved	No	Bool	true/false	Caller triggered a self-service response from the IVR and then disconnected.
ivr_abandoned	No	Bool	true/false	Caller disconnected without receiving a self-service response from IVR nor being placed in live agent queue.
agent_queue_assigned	No	String	Wireless Sales	Agent group/agent skill group (aka queue name)
time_in_queue	No	Integer	600	Seconds caller waits in queue to be assigned to an agent.
queue_abandoned	No	Bool	true/false	Caller disconnected after being assigned to a live agent queue but before being assigned to an agent.
call_handle_time	No	Integer	650	Call duration in seconds from call assignment event to call disconnect event.
call_wrap_time	No	Integer	30	Duration in seconds from call disconnect event to end of agent wrap event.
transfer	No	String	Sales Group	Agent queue name if call was transferred. NA or Null value for calls not transferred.
disposition_category	No	String	Change plan	Categorical outcome selection from agent. Alternatively, could be category like ‘Resolved’, ‘Unresolved’, ‘Transferred’, ‘Referred’.
disposition_notes	No	String		Notes from agent regarding the disposition of the call.
transaction_completed	No	String	Upgrade Completed, Payment Processed	Name of transaction type completed by call agent on behalf of customer. Could contain multiple delimited values. May not be available for all agents.
caller_account_value	No	Decimal	129.45	Current account value of customer.

Historical Transcript File Structure

ASAPP accepts uploads for historical conversation transcripts for both voice calls and chats.

The fields described below must be the columns in your uploaded .CSV table.

Each row in the uploaded .CSV table should correspond to one sent message.

FIELD NAME	REQUIRED?	FORMAT	EXAMPLE	NOTES
conversation_externalId	Yes	String	3245556677	Unique identifier for the conversation
sender_externalId	Yes	String	6433421	Unique identifier for the sender of the message
sender_role	Yes	String	agent	Supported values are ‘agent’, ‘customer’ or ‘bot’
text	Yes	String	Happy to help, one moment please	Message from sender
timestamp	Yes	Timestamp	2022-03-16T18:42:24.488424Z	ISO 8601 formatted UTC timestamp

Proper transcript formatting and sampling ensures data is usable for model training. Please ensure transcripts conform to the following:

Formatting

• Each utterance is clearly demarcated and sent by one identified sender

• Utterances are in chronological order and complete, from beginning to very end of the conversation

• Where possible, transcripts include the full content of the conversation rather than an abbreviated version. For example, in a digital messaging conversation:

  Full	Abbreviated
  Agent: Choose an option from the list below Agent: (A) 1-way ticket (B) 2-way ticket (C) None of the above Customer: (A) 1-way ticket	Agent: Choose an option from the list below Customer: (A)

Sampling

• Transcripts are from a wide range of dates to avoid seasonality effects; random sampling over a 12-month period is recommended
• Transcripts mimic the production conversations on which models will be used - same types of participants, same channel (voice, messaging), same business unit
• There are no duplicate transcripts

Sales Methods & Attribution Data File Structure

The table below shows the required fields to be included in your uploaded sales methods and attribution data.

FIELD NAME	REQUIRED?	FORMAT	EXAMPLE	NOTES
transaction_id	Yes	String	1d71dce2-a50c-11ea-bb37-0242ac130002	An identifier which is unique within the customer system to track this transaction.
transaction_time	Yes	Timestamp	2007-04-05T14:30:05.123Z	ISO 8601 formatted UTC timestamp. Details potential duplicates and also attribute to the right period of time
transaction_value_one_time	No	Float	65.25	Single value of initial purchase.
transaction_value_recurring	No	Float	7.95	Recurring value of subscription purchase.
customer_category	No	String	US	Custom category value per client.
customer_subcategory	No	String	wireless	Custom subcategory value per client.
external_customer_id	No	String	34762720001	External User ID. This is hashed version of the client ID. In order to attribute to ASAPP metadata, one of these will be required (Customer ID or Conversation ID)
issue_id	No	String	1E10412200CC60EEABBF32	IF filled in, should map to ASAPP’s system. May be empty, if the customer has not had a conversation with ASAPP. In order to attribute to ASAPP metadata, one of these will be required (Customer ID or Conversation ID)
external_session_id	Yes	String	1a09ff6d-3d07-45dc-8fa9-4936bfc4e3e5	External session id so we can track a customer
product_category	No	String	Wireless Internet	Category of product purchased.
product_subcategory	No	String	Broadband	Subcategory of product purchased.
product_name	No	String	Broadband Gold Package	The name of the product.
product_id	No	String	WI-BBGP	The identifier of the product.
product_quantity	Yes	Integer	1	A number indicating the quantity of the product purchased.
product_value_one_time	No	Float	60.00	Value of the product for one time purchase.
product_value_recurring	No	Float	55.00	Value of the product for recurring purchase.

Generate SSH Public Key Pair and Upload Files

You can generate the key and upload files via Windows, Mac, or Linux.

Windows Users

If you are using Windows, follow the steps below:

1. Generate an SSH Key Pair

There are multiple tools that you can use to generate an SSH Key Pair. For example: by using puTTYgen (available from PuTTY ) as shown below.

Choose RSA and 4096 bits, then click generate and move the mouse pointer randomly.  When the key is generated, enter sftp followed by your company marker as the key comment.

2. Provide the Public Key to ASAPP

Save the public and private key.  Only send the public file for your key pair to ASAPP.  This is not a secret and can be emailed.

3. Upload Files

Use an SFTP utility such as Cyberduck (available from Cyberduck ) to upload files to ASAPP.  Click Open Connection, add sftp.us-east-1.asapp.com as the Server,  and add sftpcompanymarker as the Username.  Choose the private key you generated in step 2 as the SSH Private Key and click connect.  The following screenshots show how to do this using Cyberduck.

A pop-up window appears. Click to allow the unknown fingerprint.  You will then see the in and out directories.

Double click the in directory and click Upload to choose files to send to ASAPP.

Mac/Linux Users

If you are using a Mac or Linux, follow the steps below:

1. Generate an SSH Key Pair

If you are using a Mac or Linux, you can generate a key pair from the terminal as follows.

If you already have an id_rsa file in the .ssh directory that you use with other applications, you should specify a different filename for the key so you do not overwrite it.  You can either do that with the -f option or type in a filename when prompted.

ssh-keygen -t rsa -b 4096 -C sftp<companymarker>; -f filename

For Example:

ssh-keygen -t rsa -b 4096 -C sftptestcompany -f keyforasapp

Where the filename will be the name of two files generated - filename (the private key you must keep to yourself) and filename.pub (the public key which ASAPP needs)

If you do not have an id_rsa file in the .ssh directory, you can go with the default filename of  id_rsa and do not need to use the -f option.

ssh-keygen -t rsa -b 4096 -C sftp<companymarker>

2. Provide the Public Key to ASAPP

Send the .pub file for your key pair to ASAPP.  This is not a secret and can be emailed.

3. Upload Files

You can upload files using the terminal or you can use Cyberduck. This section describes how to upload files using the terminal.

To login to the ASAPP server, type one of the following:

If you used the default id_rsa key name:

sftp sftp<companymarker>@sftp.us-east-1.asapp.com

If you specified a different filename for the key:

sftp -oIdentityFile=filename

sftp sftp<companymarker>@sftp.us-east-1.asapp.com

For Example:

sftp -oIdentityFile=keyforasapp

[e-mail]

You will see the command line prompt change to sftp>

If the sftp command fails, adding the -v parameter will provide logging information to help to diagnose the problem.

Use terminal commands such as ls, cd, mkdir on the remote server.

• ls: list files
• cd: change directory
• mkdir: make a new directory ls will show two directories: in (for sending files to ASAPP) and out (for receiving files from ASAPP).

To create a transcripts directory on the remote machine to send transcripts to ASAPP, type:

cd in
mkdir transcripts
cd transcripts

To navigate on the local machine, prefix terminal commands with l

• lcd: change the local directory
• lls: list local files
• lpwd: to see the local working directory

Use get (retrieve) and put (upload) to transfer files.

get will fetch files from the remote server to the current directory on the local machine.

For example:

get output.csv will transfer a file named output.csv from the remote server.

put will transfer files to the remote server from the current directory on the local machine.

Navigate to local directory with transcripts and type:

put transcripts.csv will transfer a file named transcripts.csv to the remote server.

or

put * will transfer all files in the local directory.

or

put -r <local directory> works recursively and will transfer all files in the local directory, all sub directories, and all files within them to the remote machine. 

For example:

put -r sftptest

will transfer the sftptest directory and everything within it and below it from the local machine to the remote machine.

To end the SFTP session, type quit or exit.