Skip to main content

Salesforce NPSP

Here's how to integrate Tatango with Salesforce — sync contacts, leads or accounts into Tatango, log every message sent and received on the Salesforce record, and keep opt-outs in sync.

Written by Chinmayee Baral

How to Configure the Salesforce Integration

This guide walks through how to configure the Salesforce → Tatango integration to automatically sync contacts into Tatango for SMS/MMS messaging, log every message sent and received onto the Salesforce record, and keep opt-outs synchronized back to Salesforce for compliance.

What This Integration Does

The Salesforce integration allows you to:

  • Sync contacts, leads, or accounts from Salesforce into Tatango using a Salesforce Report

  • Automatically add or update subscribers in a Tatango list on a daily schedule

  • Log every broadcast you send as an activity on that person's Salesforce record

  • Log every reply you receive on the same record, so the full conversation is visible in one place

  • Sync SMS opt-outs from Tatango back to Salesforce

  • Map Salesforce fields to Tatango custom fields for segmentation and personalization

Sync schedule: Daily at 12:00 PM Eastern

Data flow:

  • Salesforce → Tatango (scheduled report sync)

  • Tatango → Salesforce (opt-outs, within a few minutes)

  • Tatango → Salesforce (message activity, from scheduled reports)

Before You Start

You'll Need

  • A Salesforce account with:

    • Reports access

    • API access

    • Permission to read and update Contacts, Leads, or Accounts

    • Permission to create custom fields

  • A Tatango account with the Salesforce integration enabled

  • A Tatango list where subscribers will be synced

If You Want Message Activity Logged in Salesforce

Logging every text you send and receive onto the Salesforce record is optional — subscriber sync and opt-outs work without it. If you do want it, you'll additionally need:

  • A custom field on the Activity object - you'll create this in Step 1. It's what stops repeat report deliveries from duplicating messages, and it needs Salesforce admin rights.

  • Your report delivery address - ask your Tatango account manager. Worth requesting early so you're not waiting on it at the end.

  • The Recipients and/or All replies reports scheduled in Tatango — you'll set these up in Step 5.

⚠️ Important:

All Salesforce fields you want to sync (except Phone and Record ID) must already exist as custom fields in your Tatango list before setup.

Recommended Fields to Include

Required Fields

These are required for the integration to function correctly:

Salesforce Field

Tatango Field

Purpose

Contact ID / Lead ID / Account ID

contact_id / lead_id / account_id (custom field)

Required for opt-out sync, and for matching messages to the right record

Any phone field (MobilePhone, Phone, etc.)

Phone Number

Required to create/update subscribers

The phone field you map matters for more than syncing. Whichever Salesforce phone field you map to Phone Number is also the field the integration searches when matching an incoming message back to a record. Map the field your subscribers' numbers actually live in.

Strongly Recommended Fields

These fields enable personalization and segmentation:

Salesforce Field

Tatango Field

Use Case

FirstName

First Name

Message personalization

LastName

Last Name

Message personalization

Email

Email

Multi-channel coordination

MailingPostalCode

Zip Code

Geographic targeting

Recommended Giving & Engagement Fields (Nonprofits)

Salesforce Field

Tatango Custom Field

Use Case

Total_Gifts

total_gifts

Major donor segmentation

Largest_Gift

largest_gift

High-value targeting

Last_Gift_Date

last_gift_date

Lapsed donor campaigns

Donor_Status

donor_status

Active / Lapsed targeting

Recurring_Donor

recurring_donor

Sustainer messaging

Volunteer_Status

volunteer_status

Volunteer outreach

Constituent_Type

constituent_type

Board, donor, alumni, etc.

Step 1: Prepare Salesforce

Create Opt-Out Fields (If Needed)

If you don't already track SMS opt-in/opt-out status in Salesforce, create fields on the object you're syncing (Contact, Lead, or Account).

Recommended setup (Single Field)

  • Field Name: SMS Status

  • API Name: SMS_Status__c

  • Type: Picklist

  • Values: Subscribed, Unsubscribed, Unknown

Alternative (Dual Field)

  • SMS_Opt_In__c (Boolean)

  • SMS_Opt_Out__c (Boolean)

Optional

  • SMS_Opt_Out_Date__c (Date/Time)

Create the Message ID Field

Only needed if you want message activity logged in Salesforce. Skip it and subscriber sync and opt-outs still work — messages just won't appear.

Tatango gives every message its own ID. This field is where that ID is stored in Salesforce, and it's what lets a re-delivered report update an existing message instead of adding a second copy.

Setup → Object Manager → Activity → Fields & Relationships → New

  • Type: Text, length 255

  • Field Label: Tatango Message Id

  • Field Name: Tatango_Message_Id__c

  • Check External ID

  • Check Unique

⚠️ Both checkboxes are required. Salesforce can only match an existing activity through an External ID field. Without them, every report delivery adds another copy of the same message.

  • Create it on Activity, that covers both Tasks and Events, and messages are logged as Tasks.

  • Then set Field-Level Security so the Salesforce user you connect with can see the field. A field that exists but isn't visible behaves exactly like a field that doesn't exist.

Create a Salesforce Report

This report controls who is synced to Tatango.

Your report must include:

  • At least one phone field

  • Contact ID, Lead ID, or Account ID

  • Any additional fields you want to sync

Tips:

  • Use report filters to exclude board members, DNC contacts, or other segments

  • For delta updates only, filter by Last Modified Date = Yesterday

  • Run or save the report before integration setup so it appears in the selector

Report formats that work: tabular reports only.

Report formats that don't work: summary, matrix and joined reports, bucket fields, custom summary formulas, and row or column groupings.

Step 2: Prepare Tatango

Create Custom Fields in Tatango

Before starting the integration setup:

  1. Go to Lists

  2. Select your destination list

  3. Navigate to Settings → Custom Fields

  4. Create custom fields for every Salesforce field you plan to map

  5. Ensure a custom field exists for:

    • contact_id, account_id, or lead_id (required)

Field names should closely match Salesforce field names for clarity.

Name the record ID field to match your object. Use contact_id if you're syncing Contacts, lead_id for Leads, account_id for Accounts. The integration looks for that exact name when matching messages back to records.

Step 3: Configure the Integration in Tatango

Connect Salesforce

  1. Go to My Account → Integrations

  2. Select Salesforce

  3. Click Connect

  4. Log in to Salesforce and approve access

Select Object Type

Choose the Salesforce object you want to sync:

  • Contact

  • Lead

  • Account

This determines which records are updated on opt-out, and which records message activity is logged against.

One object per integration. If you want to sync Contacts and Leads, set up two separate integrations. An integration configured for one object will not match records of another.

Configure Opt-Out Logic

Choose how Tatango opt-outs update Salesforce.

Single-Field Mode

  • Select the field (e.g. SMS_Status__c)

  • Select field type

  • Enter the exact value to set on opt-out (e.g. Unsubscribed)

Dual-Field Mode

  • Select opt-in field and value (e.g. false)

  • Select opt-out field and value (e.g. true)

Optional: Enable opt-out date tracking and select a date field.

⚠️ Opt-out values are case-sensitive. If your picklist value is Unsubscribed, entering unsubscribed won't work.

Select Salesforce Report

Choose the Salesforce report you created earlier.

If you don't see it:

  • Go back to Salesforce

  • Run or save the report

  • Refresh the setup wizard

Select Tatango List

Choose the Tatango list where subscribers should be synced.

Map Fields

Required mappings:

  • Record ID → contact_id/account_id/lead_id

  • ALL phone fields → Phone Number

Optional mappings:

  • Map any additional Salesforce fields to Tatango custom fields

You can map multiple Salesforce phone fields to "Phone Number."

The integration automatically selects the first valid mobile number.

Apply a Custom Tag

After mapping fields, you can optionally configure a custom tag to be applied to every subscriber synced from this Salesforce report.

How It Works

  • Enter a string value (for example: lapsed_donors, recurring_donors, event_attendees)

  • Every subscriber added or updated by this integration instance will be tagged with that value

  • Tags are applied on every sync, ensuring they stay consistent over time

When to Use This

Custom tags are especially useful if you're running multiple instances of the Salesforce integration, such as:

  • Different donor segments (lapsed vs recurring)

  • Separate programs or campaigns

  • Distinct audiences synced from different Salesforce reports

By applying a unique tag per instance, you can:

  • Easily segment subscribers in Tatango

  • Trigger recurring or automated messages

  • Avoid overlap between audiences synced from different reports

Example

  • Report A → Tag: lapsed_donors

  • Report B → Tag: recurring_donors

Subscribers synced from each report will automatically carry the appropriate tag, even if they exist on the same Tatango list.

Step 4: Enable Opt-Out Webhook in Tatango

  1. Go to Lists

  2. Select your synced list

  3. Navigate to Settings → Webhooks

  4. Create a new webhook

  5. Paste the webhook URL provided at the end of setup

  6. Enable Unsubscribes

  7. Save

This enables opt-out updates back to Salesforce.

Step 5: Log Message Activity in Salesforce

Two Tatango reports carry message activity into Salesforce. They're independent — schedule one, the other, or both.

Report

What it logs

Appears as

Recipients

Every broadcast you send

SMS sent - <campaign>

All replies

Replies you receive, and your 1:1 responses back

SMS received / SMS sent

Both go to the same delivery address. Tatango works out which is which from the file it receives.
​

5a. Get your delivery address

Follow the steps on the integration setup screen to get the email.
​

5b. Schedule the reports

In Tatango Reports, schedule them to be delivered by email to that address. Daily is recommended. Here's an article on how to schedule reports.

⚠️ Don't rename the reports. Routing depends on the report name, so renaming All replies or Recipients stops the import.

5c. Include your record ID column

Include the custom field holding your Salesforce record ID — contact_id, lead_id or account_id, matching your object.
​

This is how messages find the right record.
​


5d. Schedule them after the daily sync

The sync runs at 12:00 PM Eastern; 2:00 PM works well. New subscribers only carry their record ID once a sync has included them.

What You'll See in Salesforce

Open a record and go to the Activity tab, then expand Past Activity. Every message appears as a completed activity.

A broadcast you sent:

SMS sent - Fall Appeal

Fall Appeal: your gift is matched today. Reply STOP to opt out.

Sent to supporter as part of a broadcast · Campaign: Fall Appeal · Delivery status: delivered

A reply you received:

SMS received - Fall Appeal

Yes! Count me in for the fall campaign.

Received from supporter · Replied to: Fall Appeal

Because both carry the campaign name, the activity timeline reads as a conversation.

Where the activity appears

This depends on the object you chose:

Object

Activity appears on

Contact

The Contact, and its Account if it has one

Lead

The Lead

Account

The Account

💡 If you don't see an Activity section on your records, ask your Salesforce administrator to add the Activity History related list to the page layout.

What Happens Next

  • Salesforce report runs daily at 12 PM Eastern

  • Contacts are added or updated in Tatango

  • Subscribers are tagged with sf_integration

  • SMS opt-outs update Salesforce fields within a few minutes

  • Message activity appears in Salesforce after each scheduled report delivery

Troubleshooting

My report doesn't appear in the dropdown

Run or save the report in Salesforce, then refresh the setup page. Salesforce only makes reports available through the API once they've been interacted with.

Also check that the report is visible to the Salesforce user you connected with.

Subscribers aren't syncing into Tatango

  • Confirm the Salesforce report returns records when you run it

  • Confirm you mapped a phone column to Phone Number

  • Confirm the phone numbers are mobile numbers — landlines and VoIP numbers can't receive SMS and are skipped

  • Confirm any Tatango custom fields you mapped to already exist on the list

Messages aren't appearing in Salesforce

  • Confirm the report is scheduled and sending to the report delivery address

  • Confirm it is still named All replies or Recipients

  • Confirm your record ID column is included in the report

  • Confirm Tatango_Message_Id__c exists on the Activity object with External ID and Unique checked, and is visible to the connected user — see Step 1

  • Confirm the daily sync has run at least once since setup

I'm seeing the same message twice on a record

This almost always means Tatango_Message_Id__c is missing, or was created without External ID and Unique checked. Correct the field in Salesforce and future deliveries will update the existing activity instead of adding another copy.

Opt-outs aren't reaching Salesforce

  • Confirm the webhook is configured on your list with Unsubscribes checked

  • Confirm the opt-out value matches your Salesforce field exactly, including capitalization and spacing

  • Confirm the field you chose still exists on the object and isn't read-only

Some people aren't being matched

Messages are matched by Salesforce record ID first, and by phone number if no ID is available.

Phone matching can't find records where the number is stored with an extension — for example 555-123-4567x890. Including your record ID column in the reports resolves this, because the ID matches exactly regardless of how the phone number is stored.

Good to Know

  • The daily sync is a full sync, not an incremental one. Your whole report is processed each day. If you'd prefer only recent changes, add a Last Modified Date = Yesterday filter to your Salesforce report.

  • Opt-outs sync one way only — from Tatango to Salesforce. Opting someone out in Salesforce does not unsubscribe them in Tatango.

  • Re-sending a report is safe. Messages already logged are updated, not duplicated.

  • Each integration syncs one report to one list, for one object. You can set up as many instances as you need.

Related Articles
Did this answer your question?