> 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.

# Configure Environment Settings

> Register or update the SDK environment used to communicate with the Conversive platform.

Use `upsertEnvironmentSettings()` to save the connection details that every downstream SDK API depends on.

## Why this API matters

This is the foundational setup step after deployment. Without valid environment settings, the SDK cannot:

* send SMS
* send MMS
* fetch account balance
* fetch plan details
* retrieve message status

## Method signature

```apex
public static ConversiveAPI.EnvironmentSettingsResponse upsertEnvironmentSettings(
    String environmentName,
    String apiKey,
    String endpointPath
)
```

## Inputs

| Parameter         | Type     | Required | Description                                                                                                                 |
| ----------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `environmentName` | `String` | Yes      | Logical name of the environment configuration. The guide recommends using `Default` for the environment used for messaging. |
| `apiKey`          | `String` | Yes      | API key used to authenticate with the Conversive platform. This value is environment-specific.                              |
| `endpointPath`    | `String` | Yes      | Base URL for the Conversive environment, such as production or QA.                                                          |

### Input example

```apex
'Default'
'your-api-key'
'https://api.beconversive.com'
```

## What the API does

This API behaves as an **upsert**:

* creates the configuration if it does not exist
* updates the configuration if it already exists

It stores:

* environment name
* API key
* endpoint URL

## Response type

```apex
public class EnvironmentSettingsResponse {
    public String response;         // SUCCESS / ERROR
    public String responseMessage;  // Human-readable message
    public Object value;            // Environment configuration result
}
```

## Response fields

| Field             | Type     | Description                                         |
| ----------------- | -------- | --------------------------------------------------- |
| `response`        | `String` | Indicates success or failure                        |
| `responseMessage` | `String` | Human-readable result                               |
| `value`           | `Object` | Created or updated environment configuration result |

## Example

```apex
try {
    ConversiveAPI.EnvironmentSettingsResponse resp =
        ConversiveAPI.upsertEnvironmentSettings(
            'Default',
            'your-api-key',
            'https://api.beconversive.com'
        );

    System.debug('Response = ' + resp.response);
    System.debug('Message = ' + resp.responseMessage);
    System.debug('Value = ' + resp.value);

} catch (Exception e) {
    System.debug('ERROR = ' + e.getMessage());
    System.debug('STACK = ' + e.getStackTraceString());
}
```

## Example response behavior

### Success

```apex
response = 'SUCCESS'
responseMessage = 'Environment settings saved successfully'
```

### Error

```apex
response = 'ERROR'
responseMessage = 'Unable to save environment settings'
```

## Documented failure behavior

The Confluence page documents **generic** failure behavior for this API rather than parameter-specific validation errors.

### Documented error outcome

* `response = 'ERROR'`
* `responseMessage` explains the reason for failure
* until the issue is fixed, the SDK may not be able to communicate with the platform

### Likely operational causes to investigate

These are the main troubleshooting areas implied by the guide:

* wrong API key
* wrong endpoint for the environment
* production credentials used with a QA endpoint
* QA credentials used with a production endpoint
* stale credentials after a key rotation

> **Important**
>
> The guide does not document exact field-level validation messages for this API beyond the generic error pattern above. The safest implementation is to validate all three inputs in your own Apex before calling the method.

## Environment guidance

### Production

Use the production API key and production base URL assigned to the production account.

### Sandbox or QA

Use the QA or sandbox API key and the corresponding non-production base URL.

## Best practices

* run this API immediately after deployment
* keep the primary messaging environment name as `Default`
* verify the connection with balance or plan APIs after saving settings
* avoid mixing credentials across environments
* rerun this API whenever credentials change