Caller Lookup

With Caller Lookup, your agent can identify the caller by their phone number before even picking up the phone. ScaleTalk automatically matches the incoming number ({{fromNumber}}) against your stored data — whether via a CSV file or an API endpoint. This allows your agent to greet the caller by name, for example, and have immediate access to customer data such as email addresses, customer numbers, or open tickets.

Activation

You can find Caller Lookup in the Agent Set-Up tab of your agent:

1. Go to Agents and open your agent
2. In the Agent Set-Up tab, scroll to the Caller Lookup section
3. Enable the Activate Caller Lookup toggle
4. Choose between CSV File (for beginners) or API Query (for advanced users)

CSV File (Beginners)

The CSV method is the easiest way to store caller data. You upload a table that contains at least one column with phone numbers — plus any number of additional columns with extra information.

How It Works

1. Download template: Click Download Template to see the expected format
2. Create CSV: Create your table in, e.g., Google Sheets or Excel. Important: Export it as a CSV file
3. Upload file: Drag the CSV file into the upload area
4. Select column separator: Choose the appropriate separator (comma or semicolon — depending on whether you use the English or German version of Google Sheets / Excel)
5. Select phone number column: Choose the column containing the phone numbers from the dropdown
6. Map variables: Assign the remaining columns to variable names of your choice. You can freely choose these names — e.g., CallerName, Email, CustomerNumber
7. Save

Example CSV

When +491701234567 calls, ScaleTalk recognizes the number and automatically makes the mapped variables (e.g., {{Name}}, {{Email}}) available.

API Query (Advanced)

With the API query, ScaleTalk can automatically call an external endpoint with every incoming call — e.g., your CRM system or an automation workflow. This allows you to access customer data dynamically and in real time.

Configuration

Step by Step

1. Set up endpoint: Create a webhook or API endpoint, e.g., in n8n, Make, or on your own server
2. Choose method: Select POST if you want to send the phone number in the body
3. Define request body: Send the {{fromNumber}} variable as JSON:

{
  "fromNumber": "{{fromNumber}}"
}

4. Test endpoint: Click Save and make a real test call. In your webhook (e.g., n8n), you can then see whether the API call was received successfully
5. Map response variables: Your endpoint returns a JSON response. Map the fields to variables via the JSON path

Example: n8n + CRM

Your n8n workflow receives the phone number, searches your CRM, and returns the customer data:

Request from ScaleTalk:

{
  "fromNumber": "+491701234567"
}

Response from your endpoint:

{
  "customer": {
    "name": "Max Mustermann",
    "email": "max@firma.de",
    "phone": "+491701234567"
  }
}

Map response variables:

Best Practices

• Fast response times: Your endpoint should respond within 2 seconds
• Use HTTPS: Always configure a secure endpoint
• Error handling: The agent works even without caller lookup data — always plan a fallback for unknown callers in the prompt
• Data minimization: Only return the data that the agent actually needs

Using Variables

The mapped variables (whether from CSV or API) can be used in three places:

1. Conversation Opener

In the Conversation Opener field, click Insert Variable and you'll see your caller lookup variables alongside the system variables. This allows you to build a personalized greeting, for example:

Hello! My name is Lisa. I can see that the name
{{CustomerName}} is showing up in my system.
Is that correct? How can I help you?

2. Prompt

You can also use the variables in the system prompt, e.g., to tell the agent how to handle known vs. unknown callers:

# Caller Identification

- If {{CustomerName}} is populated:
  Always use this name in the conversation.
  Say e.g.: "I see you are {{CustomerName}}."

- If {{CustomerName}} is empty:
  Ask: "May I ask who I'm speaking with?"

3. Follow-up

In the Follow-up configuration, you can also use the caller lookup variables — e.g., in the email summary or the webhook body. This allows you to pass on customer data such as email addresses or customer numbers directly, without the agent having to ask for them during the conversation.

System Variables

Regardless of the chosen method, the following system variables are always available: