Skip to content
  • There are no suggestions because the search field is empty.

Managing Campaign Contacts with Taalk.ai API

Learn how to manage campaign contacts in Taalk.ai using the API to add, update, or delete contacts efficiently. This guide covers endpoint details, contact data formatting, and example requests for seamless integration with Taalk's conversational AI platform.

Prerequisites

Before you proceed:

  • Ensure you have your Taalk API Key for authorization.
  • A campaign must already exist in your Taalk console.

Locating Your Campaign ID

  1. Log into the Taalk.ai Console.
  2. Navigate to Contact Center and select your campaign.
  3. Identify the campaign ID from the URL. For example:
https://lets.taalk.ai/console/campaign2s/6791043299aeedfec27f85d5

Here, the campaign ID is: 6791043299aeedfec27f85d5

Contact Data Format

When adding contacts in Taalk:

  • Required Fields: name and phone (these do NOT require any prefix).
  • Custom Fields: Must be prefixed with Taalk_ to ensure data integration with the AI agent.

For example:

  • name: "John"
  • phone: "1234567890"
  • Taalk_Address: "123 Fake St."

⚠️ IMPORTANT ⚠️

  • Field name Consistency: Field names used in contact must exactly match the required field names, including case sensitivity.
    • Example: Taalk_vehicleyear would be treated as different field from taalk_vehicleyear or TAALK_vehicleyear .
  • AI Agent Dependencies: Ensure all fields required by your AI agent are included with matching fields. Missing or mismatched fields can cause issues with data processing.
  • Tracking Information: Include any necessary tracking fields to support downstream systems and reporting.

API Endpoint for Managing Contacts

POST https://api.taalk.ai/api/campaign2s/{campaign-id}/contacts

Headers:

  • Content-Type: application/json
  • Authorization: Bearer <taalk_api_token>

Operations Supported

You can perform the following actions:

  1. Append Contacts - Add new contacts to a campaign.
  2. Update Contacts - Modify existing contact information.
  3. Remove Contacts - Delete contacts using phone numbers or contact IDs.
  4. Shuffle Contacts - Randomize the order of contacts within a campaign.

1. Adding (Appending) Contacts

Sample cURL Request

curl --location 'https://api.taalk.ai/api/campaign2s/<your-campaign-id>/contacts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <taalk_api_token>' \
--data '{
    "append": [
        {
            "name": "Toma",
            "last_name": "Kraft",
            "phone": "7047058647",
            "Taalk_Address": "123 Fake St.",
            "Taalk_City": "Charlotte",
            "Taalk_State": "NC",
            "Taalk_Zip": "28202",
            "Taalk_vehicleyear": "2025",
            "Taalk_vehiclemake": "Tesla",
            "Taalk_vehiclemodel": "3",
            "Taalk_Mileage": "20000",
            "Taalk_VIN": "somevin"
        }
    ],
    "shuffle": true
}'

Response Example

{
    "change": {
        "inserted": 1,
        "updated": 0,
        "removed": 0
    }
}

Notes:

  • The shuffle parameter, when set to true, randomizes the new contacts within the campaign.

2. Updating Contacts

Sample Request

curl --location 'https://api.taalk.ai/api/campaign2s/<campaign-id>/contacts/7047058647' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <taalk_api_token>' \
--data '{
    "Taalk_Success": true
}'

Explanation:

  • Key (7047058647): Use phone number (or contact ID) in URL identifying the contact to update.
  • Value (Taalk_Success: true): Specifies the fields on contact to be update.

3. Removing Contacts

Sample Request

curl --location 'https://api.taalk.ai/api/campaign2s/<campaign-id>/contacts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <taalk_api_token>' \
--data '{
    "remove": ["7047058647"]
}'

Explanation:

  • The remove field accepts an array of contact phone numbers or object IDs for deletion.

4. Shuffling Contacts

The shuffle parameter can be included when:

  • Appending new contacts: Shuffles only the newly added contacts.
  • Without appending: Shuffles the entire contact list within the campaign.

Example (Shuffling All Contacts):

curl --location 'https://api.taalk.ai/api/campaign2s/<campaign-id>/contacts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <taalk_api_token>' \
--data '{
    "shuffle": true
}'

Error Handling

Common response statuses:

  • 200 OK: Operation successful.
  • 400 Bad Request: Invalid input data (e.g., missing required fields).
  • 401 Unauthorized: Invalid API key.
  • 404 Not Found: Campaign or contact not found.

Best Practices

  • Always validate the contact data format before making API requests.
  • Use the shuffle option judiciously to maintain meaningful contact sequences when needed.
  • Regularly audit campaigns to ensure contact data integrity.

For more technical API details, refer to the Taalk Swagger Documentation.