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

Table of Content



logo white background.png



















































































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.