> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.conversive.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.conversive.ai/_mcp/server.

# Send Bulk SMS

> Send text-only SMS to one or more Salesforce records, with clear guidance on inputs, response fields, validation, and Message History behavior.

Use `sendBulkSMS()` to send the same text message to one or more Salesforce records.

## When to use this API

This method is intended for:

* campaign outreach
* reminders
* notifications
* announcements
* dynamic or merge-field-driven outbound text messages

When the request is accepted, the SDK creates outbound records on **Message History** and queues them for delivery.

## Method signature

```apex
public static ConversiveAPI.MessageResponse sendBulkSMS(
    List<Id> contactIds,
    String message,
    List<String> phoneList,
    Id senderId
)
```

## Inputs

| Parameter    | Type           | Required | Description                                                                  |
| ------------ | -------------- | -------- | ---------------------------------------------------------------------------- |
| `contactIds` | `List<Id>`     | Yes      | Salesforce record IDs that should receive the SMS                            |
| `message`    | `String`       | Yes      | Text content to send. Can be plain text or include merge fields              |
| `phoneList`  | `List<String>` | Yes      | Ordered list of phone field API names to inspect for recipient phone numbers |
| `senderId`   | `Id`           | Yes      | Salesforce ID of the `Sender_Id__c` record used for outbound messaging       |

### Example inputs

```apex
new List<Id>{ con1.Id, con2.Id }
'Hello, Are you interested in our new product launch telecast? Reply YES for confirmation.'
new List<String>{ 'MobilePhone', 'Phone' }
senderRec.Id
```

## How recipient resolution works

The SDK checks the fields in `phoneList` in order and uses the available phone number for delivery.

That means the developer controls:

* which fields are checked
* in what order they are checked

## Response type

```apex
public class MessageResponse {
    public String response;         // SUCCESS / ERROR
    public String responseMessage;  // Human-readable message
}
```

## Response fields

| Field             | Type     | Description                  |
| ----------------- | -------- | ---------------------------- |
| `response`        | `String` | Indicates success or failure |
| `responseMessage` | `String` | Human-readable result        |

## Validation rules

A valid request must include:

* one or more record IDs in `contactIds`
* a non-null `message`
* at least one phone field in `phoneList`
* a valid `senderId`

## Documented validation failures

The Confluence child page documents these failures:

| Condition                     | Documented result                                                                      |
| ----------------------------- | -------------------------------------------------------------------------------------- |
| `contactIds` is null or empty | `response = 'ERROR'`, `responseMessage = 'No contacts provided'`                       |
| `phoneList` is null or empty  | `response = 'ERROR'`, `responseMessage = 'At least one phone field must be provided.'` |
| `senderId` is null            | `response = 'ERROR'`, `responseMessage = 'Sender Id is required.'`                     |
| `message` is null             | `response = 'ERROR'` returned in `MessageResponse`                                     |

> **Important**
>
> The page explicitly says `message = null` returns `ERROR`, but it does **not** document the exact `responseMessage` string for that case. Do not hard-code a message string unless you verify it in the SDK implementation.

## Message processing behavior

When validation passes, the SDK:

1. validates the input parameters
2. resolves recipient numbers from `phoneList`
3. uses the provided sender record
4. creates outbound records on **Message History**
5. submits the messages to the Conversive platform

## Message status lifecycle

The Confluence page documents this status flow on **Message History**:

| Status      | Meaning                                          |
| ----------- | ------------------------------------------------ |
| `Submitted` | Message record created and queued for delivery   |
| `ERROR`     | Delivery failed during the callout to Conversive |

### Callout failure behavior

If the SDK successfully creates the record but the callout fails:

* the message is first stored as `Submitted`
* the status is later updated to `ERROR`

This is important because it separates:

* **input validation failures** returned immediately by the API
* **delivery or callout failures** that happen after record creation

## Example

```apex
Contact con1 = new Contact(
    LastName = 'Mark Smith',
    MobilePhone = '9876543210'
);

Contact con2 = new Contact(
    LastName = 'Eugene Taylor',
    MobilePhone = '9876543211'
);

insert new List<Contact>{ con1, con2 };

Sender_Id__c senderRec = new Sender_Id__c(
    Label__c = 'Sales Cadence',
    Phone__c = '9330909119'
);
insert senderRec;

ConversiveAPI.MessageResponse resp =
    ConversiveAPI.sendBulkSMS(
        new List<Id>{ con1.Id, con2.Id },
        'Hello, Are you interested in our new product launch telecast? Reply YES for confirmation.',
        new List<String>{ 'MobilePhone', 'Phone' },
        senderRec.Id
    );

System.debug('Response: ' + resp.response);
System.debug('Message: ' + resp.responseMessage);
```

## Example success response

```apex
response = 'SUCCESS'
responseMessage = 'Messages queued for delivery'
```

## Example error responses

### No contacts provided

```apex
response = 'ERROR'
responseMessage = 'No contacts provided'
```

### Missing sender ID

```apex
response = 'ERROR'
responseMessage = 'Sender Id is required.'
```

### Missing phone fields

```apex
response = 'ERROR'
responseMessage = 'At least one phone field must be provided.'
```

## What success means here

A successful `MessageResponse` means the messages were **accepted and queued**. It does not guarantee final delivery to the carrier or end recipient.

## Best practices

* validate the list of target record IDs before calling the method
* pass a valid and active sender record
* pass phone fields that actually exist on the target object
* test with a small recipient set before large sends
* inspect both the returned `MessageResponse` and related **Message History** records during troubleshooting