Table of Content



logo white background.png



















































































Talkpush API Documentation

Main Menu

Integration Help – Talkpush JSON API

Talkpush’s API allows you to instantly plug your candidate source to our platform so you can enjoy the benefits of Talkpush immediately with your existing setup!

How to create a candidate in Talkpush

If you already have your own career website and it’s been generating a great flow, you can always integrate with us by having your career website send over some crucial candidate information we require, so your candidate can receive their Talkpush interview invitation as soon as they apply on your site!

To apply to a specific Talkpush Campaign externally via our API, simply send candidate information to the following URL:

*You need to replace :id by the id of the campaign candidate is applying for

The following parameters can be send during this API call:

Mandatory Name Description
Yes api_key API KEY to identify who is using API
Yes api_secret API SECRET to identify who is using API
Yes campaign_invitation[first_name] First name of candidate
Yes campaign_invitation[last_name] Last name of candidate
Yes* campaign_invitation[user_phone_number] Phone number (without area code)
Yes* campaign_invitation[email] Email
No campaign_invitation[temporary_cv] RAW file representing candidate resume
No campaign_invitation[ source] Name of the microsite sending information
Referee Fixed
No campaign_invitation[others][referee_first_name] First Name of Referee
No campaign_invitation[others][referee_last_name] Last Name of Referee
Referee Extra
No campaign_invitation[others][referee_id] (Employee) ID of Referee
No campaign_invitation[others][referee_email] Email of Referee
No campaign_invitation[others][referee_mobile] Phone Number of Referee
No campaign_invitation[others][referee_account] Account of Referee
No campaign_invitation[others][position] Position of Referee
No campaign_invitation[others][bpo_experience] (BPO) Working experience of Refree
No campaign_invitation[others][column_title] Any extra data you wish to store

*Candidate must input at least email OR user_phone_number otherwise he wont be created on Talkpush

ATS Integration with Talkpush

Talkpush can integrate with any ATS as long as they expose an API on which we can access. The JSON structure of a candidate exchanged from Talkpush to an ATS is the following one:

"state": "hired",
"campaign_id": 12,
"id": 840,
"first_name": "Jewel",
"last_name": "Barton",
"campaign_title": "Dynamic Retail Coordinator",
"email": "",
"user_phone_number": "3448460273",
"school_name": null,
"gender": null,
"employment": [
"company": "Sanin restaurant",
"organisation_name": "Sanin restaurant",
"description": "Département de communication Travail sur la stratgeie e-marketing Retranscription écrite Français/Anglais.",
"start_date": "2017-01",
"end_date": "notApplicable"
"description": "Département Marketing PowerPoint présentation. Gestion du portefeuille client",
"start_date": "2015-08",
"end_date": "2015-08"
"description": "Département d'acuille * confirmation des réservation avec les clients.",
"start_date": "2014-07",
"end_date": "2014-07"
"description": "Travail en groupe.",
"start_date": "2013",
"end_date": "2013"
"links": [{
"url": ""
"others": {}

Talkpush can be integrated with all the leading ATS (including but not limited to Taleo, SuccessFactors, iCIMS, Lumesse, Workday, Kenexa, Jobvite, Greenhouse) and make those completed audio profiles available to all your decision makers.

Pleaes contact us at to find out more about ATS Integrations or contact your Account Manager

Traffic Ad Integration

Main Menu

Step 1: Create your Traffic Ad (traffic destination is Messenger)

traffic 1.gif

Step 2: In the Ad set up (edit mode), Click on “Set Up Messenger Content”


You can use pictures, text and buttons to deliver an engaging candidate experience.

How to edit the Messenger Content (Pop Up Screen)

Method A: Using the Quick Creation tab (faster)

  • Introductory Text: Use this as Headline (of sorts) when the candidate first arrives in messenger (after clicking the Advertisement)
  • Message Format: Option to use just Text or Image & Text
  • Fill Message Text: This should be the text that candidates see before continuing with the application. Use this to create awareness about the position and/or reinforce the requirements of the role or even list down the steps involved in the interview process.
  • Image (if “Image & Text” format is chosen): Include an image that resonates with the position(s) you are advertising, or tied to the company culture
  • Buttons: The buttons add a great visual direction to the candidates and a great tool for improving the user experience. Set up the buttons by filling the following:
  • Label: This is the text that appear on the button. You could simply have 1 button which says, “Get Started” or have multiple buttons which can redirect candidates to different job positions in the Chatbot
  • Action: You can either select “Open Website” or “Send a Postback” (“postback” allows you to send specific commands to the bot, for e.g. job selection). Basically, this specifies what the button is supposed to do
  • Website URL, if Open Website (or Payload, if Postback is selected): This fills the value of the action you selected (above). If you want the button to open a link, this field should be filled with the URL. For Talkpush Chatbot job selection, you can use the messenger URL of each job position or Talkpush campaign and candidates will be able to select the job

traffic 3.gif

Method B: Using the JSON Creation tab (for advanced users)

This tab allows you to directly edit the code behind the messenger welcome text/actions. You can set the messages, the content, the button, etc. by simply altering the source code.

traffic 4.png


All this configuration pays off in a beautiful candidate Experience, which is effortless, seamless and offers candidates increased clarity, awareness & context about the role.

traffic 5.gif

Google Sheet Integration

Main Menu

How to setup the google form properly

  1. Head over to Google Forms’ site:
  2. Log-in if you haven’t already
  3. Create a brand new form (edit questions to follow the structure below)
    • Question 1 has to be asking for the candidates’ Full Name
    • Question 2 has to be asking for their Email
    • Question 3 has to be asking for their Phone Number 

      after these 3 questions, the following is optional 

    • Question 4 has to be asking for their Location or Current Location
    • Question 5 has to be related to their Highest Level of Education
    • Question 6 has to be related to their # of years of experience 

      after this question, the following questions are only for running an ERP program 

    • Question 7 will be for the referring employee’s Name
    • Question 8 will be for the referring employee’s Email
    • Question 9 will be for the referring employee’s Phone Number
    • Question 10 will be for the referring employee’s employeeID
    • Question 11 will be for the referring employee’s account 

      after that, you may ask for any additional details for your record 

  4. Once the form is setup, switch focus to the “Responses” tab form the “Questions” tab
  5. Look for a little “google spreadsheet” icon and click on it to “Create Spreadsheet”
  6. Upon the popup “Select response destination”
    • Choose the option “Create a new spreadsheet”
  7. You will be directed to the new google spreadsheet in a new window
  8. Copy the URL from the browser’s address bar
  9. Paste the link back into Talkpush’s Add Candidate – Google Form tab
  10. Click on “Submit”
  11. Authorize Talkpush to access your spreadsheet when you’re asked to.
  12. You’ll be redirected back to Talkpush’s page afterwards and you’re done
  13. Sit and wait for candidates to signup and be automatically invited!

Here are some tips on how you should hint your candidates to fill out the form:

  • Name
    • First Name Last Name
  • Email
  • Phone Number
  • Location
    • City, Province, Country
  • Highest Level of Education
    • PhD or above, Masters, Bachelor, Highschool or below
  • Number of years of experience

  • Employee’s Name (referee)
  • Employee’s EmployeeID (referee_id)
  • Employee’s Email (referee_email)
  • Employee’s Phone Number (referee_mobile)
  • Employee’s Account (referee_account)

How to setup the google sheet properly for Talkpush to parse

If you prefer to use a google sheet directly (Internal access between different recruiters)
You may do so, following the same google sheet format, as if they were created by a google form!
To do so,

  1. Make sure the 1st column of your sheet is either storing a timestamp in the same format as google, or is empty.
  2. Starting from the second column, it will follow the same order and structure listed above.
  3. Column header doesn’t matter but the column order must be obeyed strictly
  4. Each row is a candidate, and you should never change the row order: New candidates should always be added following the last row on the list

**If you choose to manually edit the sheet, paste the information from an existing excel sheet. Typing it case by case may cause some system errors.

Facebook Lead Ad Integration

Main Menu

Understanding the relationship between Talkpush and a Facebook Lead Ad

Here’s how it works, as a Talkpush user, your company account is entitled to be integrated with 1 Facebook page. Once the Facebook Page & your Talkpush account are linked, you may then create some Facebook Lead Ads, provide Talkpush with your Lead Ad’s ID, so we can process your Leads and capture them into Talkpush.Selection_287.png

To start using this feature, follow the steps below:
Step 1 Connect your Facebook Page into Talkpush
a) Select any campaign in Talkpush, click on Add Candidates > Integration tab
b) Scroll down to the section Lead Ads and click on Login with Facebook


c) Sign into Facebook or if you’re already signed in, click on continue with your identity


d) Allow Talkpush Lead Ads to access your Facebook Page

allow accesss.png

e) When you return back to Talkpush, you’ll see a list of Facebook Pages, select the right


f) Talkpush is now asking for an Ad ID


Step 2a) Create Facebook Lead Ad (if you don’t already have one)
Create an Ad Campaign and a Lead Ad connected to a Lead form that contains at least the
following fields:

  • Full Name or First Name & Last name
  • Phone number
  • Email
  • Location

Once the Ad is created, it’ll have an Ad ID.

Step 2b) Locate the Ad ID

To find your App ID, we recommend going into your Ad’s manager and clicking into your Ad


In the Ad’s page, locate the Ad ID and copy it


Step 3 Connect the Ad to Talkpush
Once you have the ID copied, head back to Talkpush, where we left off in Step 1)

Paste the Ad ID in the field & click on submit


Once your Ad ID appears in the list below, your Ad has sucessfully inegrated with





Setting up a job posting for Facebook Messenger

Facebook Messenger


  • Facebook Bot Integration
    • Disable: The campaign will not appear in your Facebook Page Chatbot
    • Enable as a job position: The Chatbot will display this job opening with the data that’s inputed below in the Facebook Messenger. To the left you can see what the add will like in the Messenger
    • Enable as an inquiry type: Users communicating with your Chatbot will see this as an option in the Chatbot. Here they are asked to state their inquiry and told that your staff will get back to them. The inquiries will be visible within this campaign and you can respond to them directly.
  • Information segment
    • Here you may input all the information that you want the user to see in the Facebook Messenger, keep in mind though that there is a 80 character limit for each, do to the restricted size of an opening in a Messenger. For a detailed job description use the next segment.
  • Detailed Description
    • Here you may inform your potential applicants however extensively as you like.
    • When a candidate clicks on ‘View Description’ in the Chatbot he will be forwarded to this segment. On the Messenger Mobile App it will open a special window displaying the description within the add. On the Desktop version a new tab in the browser will be opened.
  • URL for candidates to apply to position directly via Messenger

Creating a new campaign

Creating a new campaign
Click on +new campaign on the top right of the welcome screen.

Basic settings

1. Input the title of the campaign you want to create, this will be the title displayed on the welcome screen and the campaign selection
2. Choose a Country for the Hotline Number, we strongly suggest selecting the country that you will run the campaign in, as this will be deciding the phone number prefix displayed on your candidate’s phones when they receive a call
3.Interview language will decide the language model will be used for transcription of the audio to text (if applicable for your campaign
4. Webdialout:Provide candidates with the option to follow a link to initiate an interview call through their browser. This has to be set up by Talkpush Engineering team
5. Auto-call, if enabled a candidate will receive a call upon being added a campaign. Ex.g. when clicking on the apply button on your career site.


Permission settings

Through this drag-&-drop interface you may choose which members of your team will have access to the campaign and can thus see it and interactive with the candidates inside it.


Message Settings

1. Select the Messages that you want to edit:

  • Invitation: The messages a candidate receives to their e-mail and/or phone in order to be invited to participate in a given campaign
  • Completion: The messages that are sent out once a candidate completes the phone interview
  • Shortlisted: When shortlisting a candidate a prompt will ask you whether you would like to notify this candidate that he was shortlisted, here you may edit said notification messages
    Tipp: You can include the next step of your recruitment process into this message e.g. “Please come to our site at abcd street for an in-persona interview”
  • Rejection: Same procedure as the Shortlisted message for the scenario in which you reject a candidate

The e-mails will be sent via a address, but will have your company name as the “Sender Name”. All template options come with predefined standards that you may use.


2. Enable/disable the message type. If enabled, messages will be automatically sent out as specified above.

3. SMS Template: Here you may write the message content that will be sent via SMS. The number of characters is important as one SMS can only contain up to 160 characters, past that you will be charged for an additional SMS. The number of preview messages to the right equals the number of SMS that will be sent out for this message.
Keep in mind that you may use the Tokens in these message in order to personalize them for every candidate.

4. E-mail Template:

This template is editable from the graphic editor or by clicking on <> you can also directly edit the html. Elaborate designs are possible like this.


The Interview Creator

The interview is split into 3 main segments.
The opening Prompt is only used in the phone interview, not in the Messenger. However even with a chatbot campaign audio files have to be uploaded.

  1. The Introduction serves to welcome the candidate to the campaign.

  1. The Privacy statement serves to inform the candidate that this interview will be recorded and shared with your recruitment team. In order for the candidate to communicate his acceptance ask him to press any key on his phone.

  1. The Instructions should explain to the user that he has 4 minutes to respond to a question after it was spoken. If he wishes to proceed he may press any button on his keyboard.

The questions consist in your selection of questions.
The general recommendation by Talkpush is to have 3 – 4 questions per Interview. More questions tend to have a negative impact on the completion rate.

By clicking on Upload you can create your questions.

The Input text of the question is the text that will be displayed in the Messenger Text and should contain the question text that is being spoken in the audio file.
When uploading a file it is important to keep in mind that Talkpush only accepts .wav & .mp3 files.
When selecting the type of answer you may choose between audio, audio/text & text. Candidates will be notified in the chatbot conversation which answer type is accepted for a given question.

The Closing prompt is meant to thank the candidate for the application and inform him about the processing thereof.


User Menu

user menu.jpg


Company Profile

Analytics & Usage Data

My Account



The Company Profile

company profile

a) Follow this link to return to your campaigns

b) In the Team panel you can see all user accounts(Manager Accounts) for your company. The Owner column indicates which user has the administrative rights of this company account and thus may access all campaigns, edit the company settings and create new user accounts. You can activate the feature to Receive Weekly Statistics Email. The further options displayed Deactivate, Delete & Transfer Company Ownership can only be triggered by the Owner account. By deactivating an account the User data remains whilst this user account will however not be accessible anymore but may be reactivated at any given time.

c) The New Manager Account button allows you to add your colleagues to your company profile by sending them an invitation mail.

d)Just like the My Account option in the user menu, this will lead you to the panel where you may edit your own user account data.

e) Here you may change some of the basic company account settings, if your account has the ownership.

Company SettingsDomains on the Domain Whitelist will be the only ones permitted to acquire user accounts within your company account, this way you can ensure that only email addresses with @[yourcompanydomain] receive access.

IPs on the IP Whitelist are the only IPs that are permitted to access your company account, this way you may block outside access.

Analytics & Usage Data

The Analytics & Usage Data panels are accessible through the user menu (mentioned in the Welcome Screen Section) and provide you with a wealth of insights into your data and usage.

You can adjust the time frame of the statistics and you’ll be able to export the data. SMS Breakdown will offer a Excel file containing information on the SMS usage per campaign.

Campaign Performance

The Overview indicates the daily added, completed, shortlisted & rejected candidates across all campaigns.


Pass & Participation Rate

The Pass Rate gives you an idea on the quality of the incoming candidates over time: Shortlisted / completed
The Participation Rate tells you the how many of the applied candidates are willing to complete the interview over time: completed / invited

Rate of completion.png

Candidate Activity

This graph shows you the average number of completed interviews at a given hour of the day. This insight is very useful to understand your candidates and gives you an opportunity to optimize your ads and engagement efforts.

candidate activity.png


User Performance

Processing Volume by User
This graph will show you how many candidates have been process broken down by your users. Indicating who’s the most active recruiter

user processing volume.png

Processing time by Recruiter
This will show you how responsive each on of your users are. The shorter the processing time, the more responsive the user it. The recommended maximum processing time is 24 hours.

processing time.png


Processing time by campaign
This will show you how long it takes for the candidates to be processed by your recruiters in respect to the days by campaign. The shorter the time, the more responsive your recruiters are on the given day.
processing time per campaign.png

User Activity
Shows you the time of day or hour of the day when your recruiters are most active (measured in shortlisting/rejecting etc. actions)

user activity.png

My Account

User settings

The User Account panel lets you edit your Manager Account data.
By selecting another language the entire interface of the software will be displayed in that language for your user account.



  • @messenger_interview_link : The link that will lead the candidate to the chatbot
  • @candidate_name : The candidate name
  • @company : The company name
  • @access_code : The candidate’s PIN to trigger the phone interview
  • @webdialout : A link for the candidate to click on and to do the phone interview via the web
  • @webdialout_skip_confirmation : Same phone interview via the web, however this will skip right ahead to the first question
  • @referee : When running an Employee Referral Program this will be the name of the person who referred the candidate

The Campaign View

Main Menu

Campaign view

Welcome to the campaign view. We’ll go through it from left to right.

Candidate List panel

candidate list

  1. Campaigns
  • Click here to select to display candidates from different campaigns or even all combined, selecting Show All
  1. Search
  • Enter a candidate’s name or ID to search for him/her
  1. Folders
  • Select to show candidates in different folders, the red bubble indicates how many candidates are in each folder.
  • The available folders are: Inbox (Candidates will be added to this folder automatically once they join the campaign) , Completed(Candidates will be moved to this folder automatically once they completed the automated interview), Shortlisted, On Hold, Rejected, Hired and further below No Campaign Invitation & No response


  1. Users
  • Here you can click on the different candidates in a given folder.
  • By scrolling down you can scroll through all candidates
  1. Filter.png
    The Filter Feature


  • Filter Candidates by a variety of measures
  • By clicking reset you can reset the filter
  1. Labels
  • By clicking the ‘+’ button you can add labels to a candidate
  • By clicking on a candidates label you can display all candidates with that label
  • Talkpush automatically labels duplicate candidates as well as candidates that have completed more than 50% of the interview. Additionally, candidates that have tried the interview will be labeled with Attempted



  • By clicking on a candidate’s picture you can ‘select’ them, or ‘deselect’ if you click again
  • Now you can click on other candidates to select them as well or click ‘Select all’Select1Select 2On the top right you may Refresh PIN Code, send Invitation Mails or Quick Replies or Label the selected candidates.select3
    • Refresh PIN Code: If a candidate has not responded to your invitation his/her PIN to activate the interview via SMS expires and he is moved to the No Response folder. This option refreshes the candidate’s PIN
    • Invitation Mail & Quick Reply: Select and send out your choice of Invitation Mail or Quick Reply to all selected candidates at once
    • Label: Label all the selected candidates

middle panel

  1. Chat History
  • Here you see the conversation with the candidate
  • The green messages contain either the Text, Audio or Video message of the candidate. Beneath it you may see the channel it came through (‘f’ here indicating Facebook) and the time it was sent at
  • The grey messages are either the Chatbot’s responses, indicated by robot image or yours
  • Orange messages are Comments and are not visible to the candidate
  1. Messages & Comments
  • You may select between writing a Message or a Comment
  1. Quick replies
  • By clicking, a menu will pop up with Quick Replies to choose from and the option to create a new Quick Reply
  • Quick Replies make use of our token system, by using tokens you will not need to personalize every message. F.ex. <%= @candidate_name %> will automatically be replaced with the candidates name when sending. {link to explanation of all tokens}
  1. Sending Channel
  • Select over which channel you would like to send the message. SMS, Facebook, WeChat etc.
  1. Actions
  • Depending on the folder and the campaign settings the following actions will be displayed here:
    • Tokens: Let’s you insert tokens into the message
    • Robocall: Trigger a phone interview call
    • Call Candidates: Call the candidate and speak to him through the software
    • Send Invitation SMS: Send the Invitation SMS as set in the campaign settings
    • Stop/Resume Bot: Stop the Chatbot or resume it

Candidate Profile Panel
Candidate section

a) Campaign Options

Add Candidate

        • You may add candidates manually following this option.
        • You may write the details and uploading a resume individually.
        • On the “CSV Parsing” tag you can upload CSV files via drag-&-drop containing candidate data. In the following format:“first name, last name, email, country code, phone number, referee” – referee being used in cases where a candidate was refereed by someone.
        • On the “CV Upload” tab you can upload CVs directly by dragging and droppingaddcandidate

Campaign Settings

  • Will lead you to the campaign settings and lets you edit the setting established during the initial campaign creation


  • Will initiate a download of an excel file containing the data of all the candidates in this particular campaign



b) Candidate Data

  • The candidates basic and contact information as well as the campaign he/she is in. With the unique candidate ID you may find a candidate in the search bar. Also, please use this ID whenever you have a question or witness an issue regarding the software. Source will tell you through which channel this candidate was added to the campaign. Added & Completed will show the dates of when the candidate was added to the campaign and when he/she completed the interview (in this example both were on the 27th of march)
  • The four buttons to the right of the candidate’s image are used to move the candidate into different folders throughout the recruitment process. You may move a candidate to the Shortlist, Rejected, On Hold or Hired folders

c) Sharing

  • Generates a link that you can send and therefore share the candidates profile with other decision stakeholders. The recipient does not need to have a Talkpush account. Once the link is generated you may adjust which information you’d like it to include by clicking on Generate Links on the top right

d) Responses

  • View and revise the candidate’s responses, in the given format(text, audio or video) along with the question text and the transcribed response(if audio)