Update Contacts to a Campaign with Taalk API

Tech 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: firstName 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:

• firstName: "John"
• lastName: "Appleseed"
• phone: "1234567890"
• Taalk_Address: "123 Fake St."

---

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": [
        {
            "firstName": "Toma",
            "lastName": "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

 

---

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