Configure Environment Settings | Conversive

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

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

'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

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

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

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

Error

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