Skip to main content

The Salesmsg API

Learn more about how to do more with the Salesmsg API.

Written by Chris Brisson

👉 Start Your 14-Day Trial 👈

Introducing the Salesmsg API

The Salesmsg API is a powerful tool that allows you to access and manipulate your data and add Salesmsg to your custom automations. Our API is built using Postman and offers improved response times and a wide range of endpoints. You can use our API to add contacts, apply tags, send messages, and more.

How to Access the API

Authentication

Our API covers multiple authentication methods:

  • PAT (Personal Access Token) authorization type is to go for in case you want to integrate your personal existing account with Salesmsg in order to extend your app’s functionality. PAT are managed by the user, which means that they are tied to a user account. This makes Personal Access Tokens a good choice for development, as well as automation purposes, when an application does only require a single Salesmessage account to manage organizations.

  • OAuth2 authorization type is to go for in case you want to allow other users to authenticate against Salesmessage in order for your app to use the issued token as well as utilize the Salesmessage’s functionality.

Personal Access Token

From your Settings page, click Personal Access Tokens, then click Create Token to generate your unique API token.

When creating a token, you will be asked to select scopes - these define exactly what the token is allowed to do. Only select the scopes your integration actually needs. See the API Scopes section for the full list.

Once your token is generated, you can start testing using our Live API Portal.

OAuth2

To configure OAuth2, go to Settings > OAuth Applications and click Create Client. When creating an OAuth client, you will also be required to select scopes that define the permissions your app is requesting.

For full details, see our API 2.2 documentation.

API Scopes

All API tokens (PAT and OAuth2) now require scopes. Scopes control exactly which endpoints your token can access. There is no longer a catch-all permission - every integration must declare exactly what it needs.

If a token tries to call an endpoint it doesn't have permission for, the API will return HTTP 403 insufficient_scope.

Scopes

Scope

Type

Description

contacts:read

read

Read contacts via Public API.

contacts:write

write

Create and update contacts via Public API.

conversations:read

read

Read conversations via Public API.

conversations:write

write

Create and update conversations via Public API.

messages:read

read

Read messages via Public API.

messages:write

write

Create and update messages via Public API.

saved-replies:read

read

Read saved-replies via Public API.

saved-replies:write

write

Create and update saved-replies via Public API.

teams:read

read

Read teams via Public API.

teams:write

write

Create and update teams via Public API.

users:read

read

Read users via Public API.

users:write

write

Create and update users via Public API.

tags:read

read

Read tags via Public API.

tags:write

write

Create and update tags via Public API.

custom-fields:read

read

Read custom-fields via Public API.

custom-fields:write

write

Create and update custom-fields via Public API.

attachments:read

read

Read attachments via Public API.

attachments:write

write

Create and update attachments via Public API.

billing:read

read

Read billing via Public API.

billing:write

write

Create and update billing via Public API.

broadcasts:read

read

Read broadcasts via Public API.

broadcasts:write

write

Create and update broadcasts via Public API.

broadcasts-recurring:read

read

Read recurring broadcasts via Public API.

broadcasts-recurring:write

write

Create and update recurring broadcasts via Public API.

toll-free:read

read

Read toll-free numbers via Public API.

toll-free:write

write

Create and update toll-free numbers via Public API.

contact-imports:read

read

Read contact imports via Public API.

contact-imports:write

write

Create and update contact imports via Public API.

integrations:read

read

Read integrations via Public API.

integrations:write

write

Create and update integrations via Public API.

conversions:read

read

Read conversions via Public API.

conversions:write

write

Create and update conversions via Public API.

follow-ups:read

read

Read follow-ups via Public API.

follow-ups:write

write

Create and update follow-ups via Public API.

groups:read

read

Read groups via Public API.

groups:write

write

Create and update groups via Public API.

keywords:read

read

Read keywords via Public API.

keywords:write

write

Create and update keywords via Public API.

numbers:read

read

Read numbers via Public API.

numbers:write

write

Create and update numbers via Public API.

numbers-landline:read

read

Read landline numbers via Public API.

numbers-landline:write

write

Create and update landline numbers via Public API.

off-hours:read

read

Read off-hours via Public API.

off-hours:write

write

Create and update off-hours via Public API.

organizations-agency:read

read

Read agency organizations via Public API.

organizations-agency:write

write

Create and update agency organizations via Public API.

organizations:read

read

Read organizations via Public API.

organizations:write

write

Create and update organizations via Public API.

organizations-invitations:read

read

Read organization invitations via Public API.

organizations-invitations:write

write

Create and update organization invitations via Public API.

role-permissions:read

read

Read role permissions via Public API.

role-permissions:write

write

Create and update role permissions via Public API.

triggers:read

read

Read triggers via Public API.

triggers:write

write

Create and update triggers via Public API.

opt-in-data-files:read

read

Read opt-in data files via Public API.

opt-in-data-files:write

write

Create and update opt-in data files via Public API.

call-history:read

read

Read call history via Public API.

call-history:write

write

Create and update call history via Public API.

voice:read

read

Read voice via Public API.

voice:write

write

Create and update voice via Public API.

website-chat:read

read

Read website chat via Public API.

website-chat:write

write

Create and update website chat via Public API.

HIPAA Organizations: Additional Requirements

If your Salesmsg organization has HIPAA enabled, there are extra steps required before a third-party integration (OAuth app) can access PHI-sensitive data through the API.

What is PHI-sensitive data?

The following scopes access Protected Health Information (PHI) and are subject to HIPAA rules:

  • conversations:read / conversations:write

  • messages:read / messages:write

  • calls:read

  • recordings:read / recordings:write

  • contacts:read / contacts:write

  • attachments:read / attachments:write

Business Associate Agreement (BAA) Requirement

Before any third-party OAuth integration can access PHI-sensitive endpoints in a HIPAA organization, a signed Business Associate Agreement (BAA) must be on file between Salesmsg and that integrator.

Important: The BAA your organization has with Salesmsg does not automatically cover third-party integrators. Each OAuth application that needs to access PHI requires its own separate BAA.

What happens without a signed BAA:

  • The integrator's token request will be blocked with HTTP 403 – "Access denied. You must have a signed Business Associate Agreement (BAA) to continue."

Note: This BAA requirement applies to third-party integrators only. Organization members accessing their own data directly via PAT are not affected.

How to Enable PHI API Access for a HIPAA Org

  1. The integrator (OAuth app owner) reaches out to Salesmsg requesting PHI API access.

  2. Salesmsg sends a BAA to the integrator for signature.

  3. Once the BAA is signed, Salesmsg records the BAA status internally.

  4. The integrator can now obtain OAuth tokens and access PHI-sensitive endpoints.

To get started, contact [email protected] or reach out via live chat.

Endpoints

The Salesmsg API covers all functionality of Salesmsg, including the following:

  • Contacts

  • Conversations

  • Messages

  • Saved replies

  • Broadcasts

  • And More.

All endpoints are covered in API 2.2 documentation.

API Documentation

Salesmsg Public API Usage with PAT and Swagger

This is step-by-step walkthrough of how to use the Salesmsg Public API with a personal access token and Swagger. Follow these instructions to authenticate and perform basic API operations such as retrieving conversations, messages, and sending replies.

1. Generate a Personal Access Token

  1. Login to Salesmsg:

    • Access your Salesmsg account.

  2. Navigate to Token Settings:

    • Go to Settings > Personal Access Token.

  3. Create a Token:

    • Click on Create Token.

    • Provide a name for the token (e.g., API Access Token).

    • NEW! Select desired scopes

    • Click Create.

  4. Copy the Token:

    • Once the token is generated, copy it for later use.

2. Access Swagger and Authorize

  1. Open Swagger:

    • Navigate to the Swagger UI page (ensure you're using version 2.2).

  2. Authorize with Token:

    • Scroll down to the Authorize button at the top of the page.

    • Paste your personal access token into the provided field.

    • Click Authorize to complete authentication.

3. Perform API Operations

a. Retrieve Conversations

  1. Find the Endpoint:

    • Locate the GET /conversations endpoint in Swagger.

  2. Test the Request:

    • Click Try it out.

    • Specify any filters (e.g., date range for messages sent/received).

    • Click Execute.

  3. View Results:

    • Review the returned data, which includes a list of conversations and their details.

b. Retrieve Messages in a Conversation

  1. Get a Conversation ID:

    • From the retrieved conversations, copy the Conversation ID.

  2. Find the Endpoint:

    • Locate the GET /conversations/{id}/messages endpoint in Swagger.

  3. Test the Request:

    • Click Try it out.

    • Paste the Conversation ID and specify parameters (e.g., the number of messages to retrieve).

    • Click Execute.

  4. View Results:

    • Review the retrieved messages, including details such as status and timestamps.

c. Send a Message

  1. Find the Endpoint:

    • Locate the POST /conversations/{id}/send endpoint in Swagger.

  2. Test the Request:

    • Click Try it out.

    • Paste the Conversation ID.

    • Enter the message content (e.g., Hello, my name is Den).

    • Click Execute.

  3. Confirm Message Sent:

    • Review the response to ensure the message was successfully sent.

d. Verify Messages Sent

  1. Retrieve Recent Messages:

    • Use the GET /conversations/{id}/messages endpoint to confirm the message appears in the conversation timeline.

  2. Execute the Request:

    • Specify the Conversation ID and click Execute.

    • Review the response to confirm the new message is listed.

4. Additional Notes

  • Use filters like date or message count to refine your requests.

  • Always test endpoints in Swagger to verify data before integrating into your application.

  • Store your personal access token securely, as it grants access to your account data.

Salesmsg Public API Usage with OAuth2 and Postman

This guide walks you through using the Salesmsg Public API with OAuth2 authorization tokens in Postman. You'll learn how to retrieve your token, import the API collection, and perform API operations like fetching conversations, retrieving messages, and sending messages.

1. Retrieve OAuth2 Token

  1. Login to Salesmsg:

    • Access your Salesmsg account and log in.

  2. Open Developer Tools:

    • Press F12 to open DevTools in your browser.

  3. Find the Token:

    • Navigate to the Application tab in DevTools.

    • Select Local Storage and locate your application storage.

    • Search for the token key in the stored data.

    • Copy the token value for use in Postman.

2. Import Salesmsg API Collection into Postman

Method 1: From Swagger JSON

  1. Retrieve Swagger JSON URL:

    • Go to Settings > Personal Access Token in Salesmsg.

    • Open the API Documentation in Swagger.

    • Copy the link to the Swagger JSON file.

  2. Import into Postman:

    • Open Postman and click Import.

    • Paste the Swagger JSON URL and click Continue.

    • Adjust settings if necessary (e.g., change folder organization from "Path" to "Text").

    • Click Import to load the collection.

  3. Verify Collection:

    • Ensure all API endpoints are visible in Postman.

Method 2: From Postman Documentation

  1. Access Postman Documentation:

    • Visit the Salesmsg website, scroll to the footer, and click the API link.

    • Scroll to the "Useful Links" section and open the Postman documentation link.

  2. Run in Postman:

    • Click Run in Postman on the documentation page.

    • Choose to open in the desktop or web version of Postman.

    • Select a workspace and click Import.

  3. Verify Collection and Environment:

    • Confirm the collection is imported. If imported via documentation, the environment variables (e.g., base URL, bearer token) are automatically set.

3. Set Environment Variables in Postman

  1. Edit Bearer Token Variable:

    • In Postman, open the imported environment.

    • Locate the Bearer Token variable.

    • Paste the copied token value into the variable field.

    • Save changes and ensure the variable is updated.

  2. Verify Base URL:

    • Confirm the Base URL variable is correct (e.g., the Salesmsg API base URL).

4. Perform API Operations

a. Retrieve Conversations

  1. Select Endpoint:

    • Locate the GET /conversations endpoint in Postman.

  2. Set Parameters:

    • Add filters, such as a date range, to retrieve specific conversations.

  3. Send Request:

    • Click Send to execute the request.

  4. View Results:

    • Review the list of conversations, including IDs and details.

b. Retrieve Messages from a Conversation

  1. Get a Conversation ID:

    • Copy the ID of a specific conversation from the results of the previous step.

  2. Select Endpoint:

    • Use the GET /conversations/{id}/messages endpoint in Postman.

  3. Set Parameters:

    • Input the Conversation ID and specify parameters (e.g., number of messages to retrieve).

  4. Send Request:

    • Click Send and review the retrieved messages.

c. Send a Message

  1. Select Endpoint:

    • Use the POST /conversations/{id}/send endpoint in Postman.

  2. Set Parameters:

    • Enter the Conversation ID.

    • Add the message body in the request payload (e.g., "Hello, how can I help you?").

  3. Send Request:

    • Click Send to execute the request.

  4. Confirm Delivery:

    • Review the response to ensure the message was successfully sent.

d. Verify Sent Messages

  1. Retrieve Recent Messages:

    • Use the GET /conversations/{id}/messages endpoint again to check for the sent message.

  2. Send Request:

    • Ensure the latest message is displayed in the response data.

5. Additional Notes

  • Use Postman's filtering options to refine API requests.

  • Keep your OAuth2 token secure, as it grants access to your account data.

  • Ensure environment variables (e.g., baseURL, bearerToken) are correctly set for seamless API operations.

Refreshing OAuth2 Tokens

To refresh an expired OAuth2 token, send a POST request to the token refresh

endpoint:

https://api.salesmessage.com/pub/v2.2/oauth/token/refresh

Request Body Parameters

Send the following parameters in a JSON object:

Parameter

Description

grant_type

Must be set to refresh_token.

client_id

Your application's client ID.

client_secret

Your application's client secret.

refresh_token

The refresh token obtained during the initial token exchange.

Example Request

POST https://api.salesmessage.com/pub/v2.2/oauth/token/refresh
Content -Type: application/json
{
"grant_type": "refresh_token",
"client_id": "your_client_id",
"client_secret": "your_client_secret",
"refresh_token": "your_refresh_token"
}

Example Response

{
"token_type": "Bearer",
"expires_in": 3600,
"access_token": "new_access_token",
"refresh_token": "new_refresh_token"
}

Important Notes

  1. The refresh_token should be securely stored and only transmitted over secure channels (e.g., HTTPS).

  2. Always validate the response to confirm the token was successfully refreshed.

Refreshing Personal Access Tokens (PAT)

To refresh a PAT, send a POST request to the PAT refresh endpoint:

https://api.salesmessage.com/pub/v2.2/oauth/personal-token/refresh

Headers

Include the following header to authenticate the request:

Authorization: Bearer <existing_PAT>

Example Request

POST https://api.salesmessage.com/pub/v2.2/oauth/personal-token/refresh

Content-Type: application/json
Authorization: Bearer existing_PAT

Example Response

{
"token_type": "Bearer",
"expires_in": 3600,
Refreshing 2"access_token": "new_personal_access_token"
}

Frequently Asked Questions

What API functions are available?

Every functionality that is available on Salesmsg is accessible via our SMS API documentation.

Do I need a subscription to use the API?

Yes, an active Salesmsg subscription is required.

Do I need to select scopes when creating a token?

Yes. All new PATs and OAuth apps require scopes to be selected. There is no catch-all permission. Only request the scopes your integration actually needs.

I'm on a HIPAA plan. Can I use the API?

Yes. HIPAA organizations can use the Public API and OAuth integrations. However, any third-party OAuth application that needs to access PHI-sensitive endpoints (messages, conversations, contacts notes, calls, attachments, recordings) must have a signed BAA with Salesmsg before access is granted. Contact [email protected] to get started.

What languages are available with the API?

We offer a wide range of languages to implement the Salesmsg API...

  • C# (.net 2.0, 3.5 or later)

  • C++ (cpprest, Qt5, Tizen)

  • Go

  • Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Google API Client Library for Java, Rest-assured)

  • Kotlin

  • Node.js (ES5, ES6, AngularJS with Google Closure Compiler annotations)

  • PHP

  • PowerShell

  • Python

  • R

  • Ruby

  • Rust (rust, rust-server)

  • Scala (akka, http4s, swagger-async-httpclient)

  • Swift (2.x, 3.x, 4.x, 5.x)

  • Typescript (Angular1.x, Angular2.x, Fetch, jQuery, Node)

  • And More.

What is a Team ID?

A Team ID is your Inbox ID and can be found here:

Need Help? ✋🏻

Contact us on live chat or send an email to us at [email protected].

Related Articles
Send texts from ActiveCampaign Automations (CX Apps)
Integrating with Make
Salesmsg Salesforce Package Release Notes
Salesmsg Integrations
HIPAA Compliance in Salesmsg
Did this answer your question?