NAV

Introduction

Welcome to the msgboxx API documentation.

This documentation is provided for the public api of msgboxx. If you are using the Zapier integration the base entities are shared and hence the documentation below is relevant.

API for integrating the msgboxx messaging platform into your website or application. The API is restful and aligned to the business terminology used throughout the msgboxx application. The key entities used are APIAccount, Inbox, Contact, Message, Template, and Broadcast. Messages sent through the API have to conform to the same rules as the UI, a Message (session message) can only be sent in the 24 hour following receiving a message from the end user. If the window is not open then use the Broadcast service to send Template messages instead.

If you find any issues with this documentation, or you find any faults/issues with using our API or Zapier integration please contact support@msgboxx.io

Recent Changes

27/06/2025 - Updated API to support tags on Contact endpoints.

13/02/2025 - Updated Login API with additional http header for identifying clients

14/10/2024 - Updated messages endpoints to return additional flags for isSent, isDelivered, and isRead.

12/08/2024 - We have made the following changes to the api. New endpoint to return a list of all the users in the system /user New endpoint to return a list of all the teams in the system /team New endpoints to get/update a conversation, using above 2 endpoints allows automated assignment of conversations.

4/12/2023 - We have made the following changes to the api. By default all endpoints now support paging, with the page size set to 100. On the message endpoint, we will now only return the most recent 24 hours of data. Additional filtering params (fromDate and toDate) are available if you require more data, although data will still be paged.

Authentication

Before you can use any of our public API endpoints you will need to get a Bearer token from our authentication endpoint. All authentication is on the basis of a msgboxx user and the permissions you get in the api are exactly the same as if the user logged directly into the msgboxx platform.

To get an authentication token see the document for Token endpoint. The token endpoint now requires an additional http header X-Calling-Application which allows us to identify your application calling into our api and apply relavant rate limiting.

The token api should not be called every time you want to make a call to any api endpoint, it shoud be called once, and the resulting token stored and reused until it expires. Check the expires_at value of the result, or the exp value in the acceess_token.

All of the common scenarios below require you to have obtained a bearer token above, and send it through to all API calls.

Authorisation: Bearer mytokengoeshere

Integrations

The msgboxx platform contains 3 different public integrations to support different requirements.

Public API

The majority of the documentation below is related to our public api. This api is designed to be consumed by your back end application allowing you to easily consume our services. Functionality is provided allowing you to query all the key elements of the platform and to then either send a session message or a broadcast to a contact.

Zapier

Zapier is a no-code integration platform that allows you to easily consume our services. Zapier supports our standard authentication, and then supports both Triggers and Actions. Triggers allow you to perform an action when something in our platform is created, and Actions allow you to perform an action.

The Triggers include when a new Message, Contact, Broadcast, APIAccount, or Template are added to the system. The Actions you can take include Creating a new Contact, Message, or Broadcast, and performing searches on Contacts and Templates.

In all cases the entities in Zapier are consistent with the entities described elsewhere in this documentation.

Webhooks

The platform supports webhooks to also allow you to easily integrate actions into your own platform. We support webhooks that fire based on the same Triggers as Zapier, namely when a new Message, Contact, Broadcast, APIAccount, or Template are added to the system. Webhooks are setup by organisation administrators in the settings/webhooks section of the platform.

In all cases the entities in the Webhooks are also consistent with the entities described elsewhere in this documentation.

Token

Retrieve an Authentication Token

var myHeaders = new Headers();
myHeaders.append("content-type", "application/json");
myHeaders.append("X-Calling-Application", "My Application Name Here");

var raw = JSON.stringify({
  username: "my@username.com",
  password: "MySuperSecurePassw0rd!",
});

var requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/oauth/token", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
  "access_token": "string",
  "token_type": "string",
  "scope": "string",
  "expires_at": "string"
}

This endpoint retrieves a JWT access token and refresh token allowing to interact with the api. The access token and associated details are sent in the response body. The refresh token is sent in a secure cookie called refreshToken.

Retrieve Token HTTP Request

POST https://api.msgboxx.io/oauth/token

Retrieve Token JSON body

Parameter Description
username The username of the user you want to login into the api as
password The password for the user

Retrieve Token HTTP Responses

Code Description
200 OK
400 Bad request. please supply valid username and password

ApiAccounts

Get ApiAccounts

var myHeaders = new Headers();
myHeaders.append("Authorization", `Bearer ${bearerToken}`);

var requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/apiaccount", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
  "items": [
    {
      "apiAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "phoneNumber": "string",
      "name": "string",
      "datetime": "2023-06-27T10:22:24.427Z"
    }
  ],
  "paging": {
    "recordCount": 1,
    "pages": 1
  }
}

This endpoint retrieves all api accounts from the system that the user has access to.

Get ApiAccounts HTTP Request

GET https://api.msgboxx.io/apiaccount

Get ApiAccounts HTTP Responses

Code Description
200 OK
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.

Get API Account

var myHeaders = new Headers();
myHeaders.append("Authorization", `Bearer ${bearerToken}`);

var requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/apiaccount/3fa85f64-5717-4562-b3fc-2c963f66afa6", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
  "apiAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "phoneNumber": "string",
  "name": "string",
  "datetime": "2023-06-27T10:22:58.887Z"
}

This endpoint retrieves a specific apiaccount which will be returned if the user has access to it.

Get APIAccount HTTP Request

GET https://api.msgboxx.io/apiaccount/<apiaccountId>

Get APIAccount URL Parameters

Parameter Description
apiaccountId The Id of the api account to retrieve

Get APIAccount HTTP Responses

Code Description
200 OK
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.

Broadcasts

Get Broadcasts

var myHeaders = new Headers();
myHeaders.append("Authorization", `Bearer ${bearerToken}`);

var requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/broadcast", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
  "items": [
    {
      "broadcastId": "84ca7cae-b7aa-47da-bafa-b9bb4acd2c7e",
      "apiAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "contactId": "a38f0fc8-cb26-4266-bbd9-35eb8dbd6947",
      "messageId": "ce2400ec-f80a-4509-bcd3-5aa5a96a4bdf",
      "message": "Hi Jack, thanks for the conversation earlier about the 2 bedroom house in Swindon lets catch up soon.",
      "status": "Sent",
      "dateTime": "2022-07-05T20:13:22.263Z"
    }
  ],
  "paging": {
    "recordCount": 1,
    "pages": 1
  }
}

This endpoint retrieves all broadcasts from the system that the user has access to.

Get Broadcasts HTTP Request

GET https://api.msgboxx.io/broadcast

Get Broadcasts Query Parameters

Parameter Default Description
page The page number required
apiAccountId The unique identifier of the APIAccountId associated to the Messages
inboxId The unique identifier of the Inbox associated to the Messages
contactId The unique identifier of the ContactId associated to the Messages

Get Broadcasts HTTP Responses

Code Description
200 OK
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.

Get Broadcast

var myHeaders = new Headers();
myHeaders.append("Authorization", `Bearer ${bearerToken}`);

var requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/broadcast/84ca7cae-b7aa-47da-bafa-b9bb4acd2c7e", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
  "broadcastId": "84ca7cae-b7aa-47da-bafa-b9bb4acd2c7e",
  "apiAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "contactId": "a38f0fc8-cb26-4266-bbd9-35eb8dbd6947",
  "messageId": "ce2400ec-f80a-4509-bcd3-5aa5a96a4bdf",
  "message": "Hi Jack, thanks for the conversation earlier about the 2 bedroom house in Swindon lets catch up soon.",
  "status": "Sent",
  "dateTime": "2022-07-05T20:13:22.263Z"
}

This endpoint retrieves a specific broadcast which will be returned if the user has access to it.

Get Broadcast HTTP Request

GET https://api.msgboxx.io/broadcast/<broadcastId>

Get Broadcast URL Parameters

Parameter Description
broadcastId The Id of the broadcast to retrieve

Get Broadcast HTTP Responses

Code Description
200 OK
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.

Create Broadcast

var myHeaders = new Headers();
myHeaders.append("content-type", "application/json");

var raw = JSON.stringify({
  apiAccountId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  contactId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  templateId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  message: "Hi Jack, thanks for the conversation earlier about the 2 bedroom house in Swindon lets catch up soon.",
});

var requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/broadcast", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
  "broadcastId": "84ca7cae-b7aa-47da-bafa-b9bb4acd2c7e",
  "apiAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "contactId": "a38f0fc8-cb26-4266-bbd9-35eb8dbd6947",
  "messageId": "ce2400ec-f80a-4509-bcd3-5aa5a96a4bdf",
  "message": "Hi Jack, thanks for the conversation earlier about the 2 bedroom house in Swindon lets catch up soon.",
  "status": "Sent",
  "dateTime": "2022-07-05T20:13:22.263Z"
}

This endpoint creates a new broadcast message in the api account specified. Templates are configured on the system and have to be approved by WhatsApp. They are standard phrases which have placeholders in them which need to be replaced. Before calling the create broadcast endpoint you will need to query to find the template you want to send, get the text from it, and perform the placeholder replacements. Note due to the asynchronous nature of the platform you will always be returned the broadcastId, but not always get the messageId, message and status fields until the message is actually queued for delivery to WhatsApp.

Create Broadcast HTTP Request

POST https://api.msgboxx.io/broadcast

Create Broadcast JSON Body

Parameter Description
apiAccountId The api account of the sender
contactId The id of the contact we want to send the message to
templateId The id of the template used to format the message
message The session message we wish to send.

Create Broadcast HTTP Responses

Code Description
201 Created
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.
409 Duplicate Contact attempted - contact mobileNumber must be unique per apiAccount

Contacts

Get Contacts

var myHeaders = new Headers();
myHeaders.append("Authorization", `Bearer ${bearerToken}`);

var requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/contact", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
  "items": [
    {
      "contactId": "17b5c90a-7465-1097-b2db-66afa62c963f",
      "mobileNumber": "+447902111123",
      "name": "Test Customer",
      "status": "Subscribed",
      "email": "customer@somewhere.com",
      "apiAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "datetime": "2022-07-05T20:09:58.341Z",
      "tags": []
    },
    {
      "contactId": "a38f0fc8-cb26-4266-bbd9-35eb8dbd6947",
      "mobileNumber": "+447902875098",
      "name": "Miss Customer",
      "status": "Subscribed",
      "email": "miss@somewhereelse.com",
      "apiAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "datetime": "2022-07-05T20:09:58.341Z",
      "tags": ["customer", "prospect]
    }
  ],
  "paging": {
    "recordCount": 2,
    "pages": 1
  }
}

This endpoint retrieves all contacts from the system that the user has access to.

Get Contacts HTTP Request

GET https://api.msgboxx.io/contact

Get Contacts Query Parameters

Parameter Default Description
page The page number required
apiAccountId The unique identifier of the APIAccountId requested
mobileNumber The mobile number to search for
fromDate Filters the contacts after this date/time
toDate Filters the contacts before this date/time

Get Contacts HTTP Responses

Code Description
200 OK
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.

Get Contact

var myHeaders = new Headers();
myHeaders.append("Authorization", `Bearer ${bearerToken}`);

var requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/contact/17b5c90a-7465-1097-b2db-66afa62c963f", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
  "contactId": "17b5c90a-7465-1097-b2db-66afa62c963f",
  "mobileNumber": "+447902111123",
  "name": "Test Customer",
  "status": "Subscribed",
  "email": "customer@somewhere.com",
  "apiAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "datetime": "2022-07-05T20:09:58.341Z",
  "tags": []
}

This endpoint retrieves a specific contact which will be returned if the user has access to it.

Get Contact HTTP Request

GET https://api.msgboxx.io/contact/<contactId>

Get Contact URL Parameters

Parameter Description
contactId The Id of the contact to retrieve

Get Contact HTTP Responses

Code Description
200 OK
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.

Create Contact

var myHeaders = new Headers();
myHeaders.append("content-type", "application/json");

var raw = JSON.stringify({
  mobileNumber: "+4479051337665",
  name: "new contact",
  status: "Presubscribed",
  apiAccountId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
});

var requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/contact", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
  "contactId": "17b5c90a-7465-1097-b2db-66afa62c963f",
  "mobileNumber": "+447902111123",
  "name": "Test Customer",
  "status": "Subscribed",
  "email": "customer@somewhere.com",
  "apiAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "datetime": "2022-07-05T20:09:58.341Z",
  "tags": []
}

This endpoint creates a new contact in the api account specified

Create Contact HTTP Request

POST https://api.msgboxx.io/contact

Create Contact JSON Body

Parameter Description
mobileNumber The mobile number, must be in ISO format eg +4479051337665
name The name of the contact to create
status The status (should be Presubscribed)
email The email of the contact (optional)
apiAccountId The Id of the api account to add the contact to

Create Contact HTTP Responses

Code Description
201 Created
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.
409 Duplicate Contact attempted - contact mobileNumber must be unique per apiAccount

Update Contact

var myHeaders = new Headers();
myHeaders.append("content-type", "application/json");

var raw = JSON.stringify({"contactId": "17b5c90a-7465-1097-b2db-66afa62c963f",
  "mobileNumber": "+447902111123",
  "name": "Test Customer",
  "status": "Subscribed",
  "email": "customer@somewhere.com",
  "apiAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "datetime": "2022-07-05T20:09:58.341Z",
  "tags": [ "prospect" ]
  });

var requestOptions = {
  method: "PUT",
  headers: myHeaders,
  body: raw,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/contact/17b5c90a-7465-1097-b2db-66afa62c963f", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
  "contactId": "17b5c90a-7465-1097-b2db-66afa62c963f",
  "mobileNumber": "+447902111123",
  "name": "Test Customer",
  "status": "Subscribed",
  "email": "customer@somewhere.com",
  "apiAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "datetime": "2022-07-05T20:09:58.341Z",
  "tags": [ "prospect" ]
}

This endpoint updates a specific contact if the user has access to it.

Update Contact HTTP Request

PUT https://api.msgboxx.io/contact/<contactId>

Update Contact URL Parameters

Parameter Description
contactId The Id of the contact to update

Update Contact HTTP Responses

Code Description
200 OK
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.

Conversation

Get Conversation

var myHeaders = new Headers();
myHeaders.append("Authorization", `Bearer ${bearerToken}`);

var requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/conversation/6bea4b13-e818-4544-8c43-e28a5c6cb67f", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
    "user": {
      "firstName": "joe",
      "lastName": "bloggs",
      "userId": "f771cea9-cae7-4155-aff9-199ca1fcc690"
    },
    "team": {
        "name": "Clevedon Lettings",
        "description": "Handles all the lettings operations for the Clevedon branch.",
        "teamId": "ba8ed474-11d2-4e40-a35d-61c25ec5b894"
    },
    "folder": "inbox"
}

This endpoint retrieves a specific conversation which will be returned if the user has access to it. The only details returned are the user who the conversation is assigned to OR the department who its assigned to. Will never return both. The folder will be one of the following inbox, archive, spam.

Get Conversation HTTP Request

GET https://api.msgboxx.io/conversation/<conversationId>

Get Conversation URL Parameters

Parameter Description
conversationId The Id of the conversation to retrieve

Get Conversation HTTP Responses

Code Description
200 OK
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.

Update Conversation

var myHeaders = new Headers();
myHeaders.append("content-type", "application/json");

var raw = JSON.stringify({
    "userId": "90be5367-b922-488a-b95f-9656b369ecf7",
    "teamId": "",
    "folder": "inbox"
});

var requestOptions = {
  method: "PUT",
  headers: myHeaders,
  body: raw,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/conversation/6bea4b13-e818-4544-8c43-e28a5c6cb67f", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns an empty response body.

This endpoint updates a specific conversation if the user has access to it. The only details which can be changed are the user who the conversation is assigned to OR the department who its assigned to and the folder that the conversation is in. You can’t assign to both person and team. Use the /team and /user endpoints to work out the valid combinations of user or team that you can assign this conversation to. The valid folder names are inbox, archive, spam. All values are optional, only supply the data that you wish to change. If assigning to a person, just send the userId, if moving to archive just send through the folder: archive.

Update Conversation HTTP Request

PUT https://api.msgboxx.io/conversation/<conversationId>

Update Conversation URL Parameters

Parameter Description
conversationId The Id of the conversation to retrieve

Update Conversation HTTP Responses

Code Description
200 OK
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.

Inboxes

Get Inboxes

var myHeaders = new Headers();
myHeaders.append("Authorization", `Bearer ${bearerToken}`);

var requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/inbox", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
  "items": [
    {
      "inboxId": "84ca7cae-b7aa-47da-bafa-b9bb4acd2c7e",
      "apiAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "my inbox",
      "dateTime": "2022-07-05T20:13:22.263Z"
    }
  ],
  "paging": {
    "recordCount": 1,
    "pages": 1
  }
}

This endpoint retrieves all inboxes from the system that the user has access to.

Get Inboxes HTTP Request

GET https://api.msgboxx.io/inbox

Get Inboxes Query Parameters

Parameter Default Description
page The page number required
apiAccountId The unique identifier of the inbox associated with the APIAccountId supplied

Get Inboxes HTTP Responses

Code Description
200 OK
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.

Get Inbox

var myHeaders = new Headers();
myHeaders.append("Authorization", `Bearer ${bearerToken}`);

var requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/inbox/84ca7cae-b7aa-47da-bafa-b9bb4acd2c7e", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
  "inboxId": "84ca7cae-b7aa-47da-bafa-b9bb4acd2c7e",
  "name": "my inbox",
  "apiAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "datetime": "2023-06-21T11:58:09.668Z"
}

This endpoint retrieves a specific inbox which will be returned if the user has access to it.

Get Inbox HTTP Request

GET https://api.msgboxx.io/inboxes/<inboxId>

Get Inbox URL Parameters

Parameter Description
inboxId The Id of the inbox to retrieve

Get Inbox HTTP Responses

Code Description
200 OK
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.

Messages

Get Messages

var myHeaders = new Headers();
myHeaders.append("Authorization", `Bearer ${bearerToken}`);

var requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/message?page=1", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
  "items": [
    {
      "messageId": "ce2400ec-f80a-4509-bcd3-5aa5a96a4bdf",
      "bodyText": "anything",
      "apiAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "dateTime": "2024-04-30T14:03:25.06359+00:00",
      "conversationId": "6bea4b13-e818-4544-8c43-e28a5c6cb67f",
      "fileLocation": "",
      "messageDirection": "outgoing",
      "isTemplateMessage": false,
      "isSent": true,
      "isDelivered": true,
      "isRead": false,
      "contact": {
        "contactId": "17b5c90a-7465-1097-b2db-66afa62c963f",
        "mobileNumber": "+447902111123",
        "name": "Test Customer",
        "status": "Subscribed",
        "apiAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      },
      "senderFirstName": "firstname",
      "senderLastName": "lastname"
    }
  ],
  "paging": {
    "recordCount": 1,
    "pages": 1
  }
}

This endpoint retrieves all messages from the system that the user has access to.

Get Messages HTTP Request

GET https://api.msgboxx.io/message

Get Messages Query Parameters

Parameter Default Description
page The page number required
apiAccountId The unique identifier of the APIAccountId associated to the Messages
inboxId The unique identifier of the Inbox associated to the Messages
contactId The unique identifier of the ContactId associated to the Messages
conversationId The unique identifier of the ConversationId associated to the Messages
fromDate Filters the messages after this date/time
toDate Filters the messages before this date/time

Get Messages HTTP Responses

Code Description
200 OK
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.

Get Message

var myHeaders = new Headers();
myHeaders.append("Authorization", `Bearer ${bearerToken}`);

var requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/message/ce2400ec-f80a-4509-bcd3-5aa5a96a4bdf", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
  "messageId": "ce2400ec-f80a-4509-bcd3-5aa5a96a4bdf",
  "bodyText": "anything",
  "apiAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "dateTime": "2024-04-30T14:03:25.06359+00:00",
  "conversationId": "6bea4b13-e818-4544-8c43-e28a5c6cb67f",
  "fileLocation": "",
  "messageDirection": "outgoing",
  "isTemplateMessage": false,
  "isSent": true,
  "isDelivered": true,
  "isRead": false,
  "contact": {
    "contactId": "17b5c90a-7465-1097-b2db-66afa62c963f",
    "mobileNumber": "+447902111123",
    "name": "Test Customer",
    "status": "Subscribed",
    "apiAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "senderFirstName": "firstname",
  "senderLastName": "lastname"
}

This endpoint retrieves a specific message which will be returned if the user has access to it.

Get Message HTTP Request

GET https://api.msgboxx.io/message/<messageId>

Get Message URL Parameters

Parameter Description
messageId The Id of the message to retrieve

Get Message HTTP Responses

Code Description
200 OK
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.

Create Message

var myHeaders = new Headers();
myHeaders.append("content-type", "application/json");

var raw = JSON.stringify({
  message: "Hi John, that sounds good progress, keep me informed please.",
  apiAccountId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  contactId: "17b5c90a-7465-1097-b2db-66afa62c963f",
});

var requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/contact", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
  "messageId": "ce2400ec-f80a-4509-bcd3-5aa5a96a4bdf",
  "bodyText": "Hi John, that sounds good progress, keep me informed please.",
  "apiAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "dateTime": "2024-04-30T14:03:25.06359+00:00",
  "conversationId": "6bea4b13-e818-4544-8c43-e28a5c6cb67f",
  "fileLocation": "",
  "messageDirection": "outgoing",
  "isTemplateMessage": false,
  "isSent": false,
  "isDelivered": false,
  "isRead": false,  
  "contact": {
    "contactId": "17b5c90a-7465-1097-b2db-66afa62c963f",
    "mobileNumber": "+447902111123",
    "name": "Test Customer",
    "status": "Subscribed",
    "apiAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "senderFirstName": "firstname",
  "senderLastName": "lastname"
}

This endpoint creates a new session message in the api account specified. Sending a session message has a number of mandatory data items including the api account you are sending from, the contact you are sending to, and the actual text you are sending. These examples assume you only have access to a single inbox and api account. Note due to the asynchronous nature of the platform the status will update as the message is sent, delivered and read.

Create Message HTTP Request

POST https://api.msgboxx.io/message

Create Message JSON Body

Parameter Description
apiAccountId The api account of the sender
contactId The id of the contact we want to send the message to
message The session message we wish to send.

Create Message HTTP Responses

Code Description
201 Created
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.
409 Duplicate Contact attempted - contact mobileNumber must be unique per apiAccount

Teams

Get Teams

var myHeaders = new Headers();
myHeaders.append("Authorization", `Bearer ${bearerToken}`);

var requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/team", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

[
    {
        "name": "Contract Recruitment",
        "description": "Handles all contractor engagements",
        "teamId": "fbbb761a-091a-4273-bc7f-0f616a607ae7",
        "apiAccounts": [
            {
                "name": "Stitch Recruit Contract",
                "apiAccountid": "7f2280ed-40bd-4bba-a813-a833f022cdf9"
            },
        ],
        "users": [
            {
                "firstName": "contract",
                "lastName": "recruiter",
                "userId": "6d73d10d-ada8-4de2-a9a6-f441ab344287"
            }
        ]
    },
    {
        "name": "Head Office",
        "description": "Accounts, billing, etc",
        "teamId": "dac042bb-31b6-41fe-b70a-20f5d73c0464",
        "apiAccounts": [
            {
                "name": "Head Office",
                "apiAccountid": "3aa9eb0c-7e55-4e98-9ce7-bd6d241d0ad4"
            }
        ],
        "users": [
            {
                "firstName": "john",
                "lastName": "smith",
                "userId": "8492a9d3-af16-4375-ba7c-9f67325a6a3d"
            },
            {
                "firstName": "rory",
                "lastName": "mcilroy",
                "userId": "cd30d620-9a0e-428d-86a6-acaa54be9b72"
            },
        ]
    },
    {
        "name": "Permie Recruitment",
        "description": "Handles all the permanent side of our recruitment business",
        "teamId": "1333edd0-69f0-40ef-a944-ba530ea32f60",
        "apiAccounts": [
            {
                "name": "Stitch Recruit Permanent",
                "apiAccountid": "cbe2b1f5-e732-459c-982b-541e4f134cb3"
            }
        ],
        "users": [
            {
                "firstName": "john",
                "lastName": "jones",
                "userId": "6d73d10d-ada8-4de2-a9a6-f441ab344287"
            },
                        {
                "firstName": "helen",
                "lastName": "smith",
                "userId": "19d9be10-1d9c-4d9c-82d6-974c12aa0a93"
            }
        ]
    }
]

This endpoint retrieves all teams from the system. Teams can be linked to one of more apiAccounts or can be global. Users of the system are grouped into the teams.

Get Teams HTTP Request

GET https://api.msgboxx.io/team

Get Teams Query Parameters

No parameters, teams is predominantely static data.

Get Teams HTTP Responses

Code Description
200 OK
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.

Templates

Get Templates

var myHeaders = new Headers();
myHeaders.append("Authorization", `Bearer ${bearerToken}`);

var requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/template", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
  "items": [
    {
      "templateId": "0bbadd13-0e3f-4ebb-9f65-9e6ee460d7ba",
      "apiAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "Approved",
      "name": "follow_up",
      "templateText": "Hi {{1}}, thanks for the conversation earlier about {{2}} lets catch up soon.",
      "templateExample": "Hi [John], thanks for the conversation earlier about [the 2 bedroom house you are interested in,] lets catch up soon.",
      "dateTime": "2022-07-05T20:13:22.260Z"
    }
  ],
  "paging": {
    "recordCount": 1,
    "pages": 1
  }
}

This endpoint retrieves all templates from the system that the user has access to.

Get Templates HTTP Request

GET https://api.msgboxx.io/template

Get Templates Query Parameters

Parameter Default Description
page The page number required
apiAccountId The unique identifier of the APIAccountId associated to the templates
name The name of the template required

Get Templates HTTP Responses

Code Description
200 OK
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.

Get Template

var myHeaders = new Headers();
myHeaders.append("Authorization", `Bearer ${bearerToken}`);

var requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/template/0bbadd13-0e3f-4ebb-9f65-9e6ee460d7ba", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
  "templateId": "0bbadd13-0e3f-4ebb-9f65-9e6ee460d7ba",
  "apiAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "Approved",
  "name": "follow_up",
  "templateText": "Hi {{1}}, thanks for the conversation earlier about {{2}} lets catch up soon.",
  "templateExample": "Hi [John], thanks for the conversation earlier about [the 2 bedroom house you are interested in,] lets catch up soon.",
  "dateTime": "2022-07-05T20:13:22.260Z"
}

This endpoint retrieves a specific template which will be returned if the user has access to it.

Get Template HTTP Request

GET https://api.msgboxx.io/template/<templateId>

Get Template URL Parameters

Parameter Description
templateId The Id of the template to retrieve

Get Template HTTP Responses

Code Description
200 OK
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.

Users

Get Users

var myHeaders = new Headers();
myHeaders.append("Authorization", `Bearer ${bearerToken}`);

var requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/user", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

[
    {
        "user": {
            "firstName": "contract",
            "lastName": "recruiter",
            "userId": "6d73d10d-ada8-4de2-a9a6-f441ab344287"
        },
        "apiAccount": {
            "name": "Stitch Recruit Contract",
            "apiAccountid": "7f2280ed-40bd-4bba-a813-a833f022cdf9"
        }
    },
    {
        "user": {
            "firstName": "john",
            "lastName": "smith",
            "userId": "8492a9d3-af16-4375-ba7c-9f67325a6a3d"
        },
        "apiAccount": {
            "name": "Head Office",
            "apiAccountid": "3aa9eb0c-7e55-4e98-9ce7-bd6d241d0ad4"
        }
    },
    {
        "user": {
            "firstName": "rory",
            "lastName": "mcilroy",
            "userId": "5aff12a0-9e91-43a6-8e68-8cce3a76f749"
        },
        "apiAccount": {
            "name": "Head Office",
            "apiAccountid": "3aa9eb0c-7e55-4e98-9ce7-bd6d241d0ad4"
        }
    },
    {
        "user": {
            "firstName": "john",
            "lastName": "jones",
            "userId": "6d73d10d-ada8-4de2-a9a6-f441ab344287"
        },
        "apiAccount": {
            "name": "Stitch Recruit Permanent",
            "apiAccountid": "cbe2b1f5-e732-459c-982b-541e4f134cb3"
        }
    },
    {
        "user": {
            "firstName": "helen",
            "lastName": "smith",
            "userId": "19d9be10-1d9c-4d9c-82d6-974c12aa0a93"
        },
        "apiAccount": {
            "name": "Stitch Recruit Permanent",
            "apiAccountid": "cbe2b1f5-e732-459c-982b-541e4f134cb3"
        }
    }
]

This endpoint retrieves all users from the system. Users are linked to the apiAccounts which they have access to.

Get Users HTTP Request

GET https://api.msgboxx.io/user

Get Users Query Parameters

No parameters, users is predominantely static data.

Get Users HTTP Responses

Code Description
200 OK
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.

Webhooks

Get Webhooks

var myHeaders = new Headers();
myHeaders.append("Authorization", `Bearer ${bearerToken}`);

var requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/webhook", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
  "items": [
            {
            "webhookId": "dab932d2-c490-48de-96a4-f76848241597",
            "type": "contact",
            "targetUrl": "https://hooks.zapier.com/hooks/standard/11043413/21d7b275de264bf9aee14a52de22a17d/",
            "isEnabled": true,
            "failureCount": 0,
            "isZapier": true
        },
        {
            "webhookId": "a1a39245-66e8-4b4a-9ebc-cdebc14b08ff",
            "type": "message",
            "targetUrl": "https://webhook.site/7cf42801-b236-4dcd-86f2-24d249de484c",
            "isEnabled": false,
            "failureCount": 0,
            "isZapier": false
        }
  ],
  "paging": {
    "recordCount": 2,
    "pages": 1
  }
}

This endpoint retrieves all webhooks from the system that the user has access to.

Get Webhooks HTTP Request

GET https://api.msgboxx.io/webhooks

Get Webhooks Query Parameters

Parameter Default Description
page The page number required

Get Webhooks HTTP Responses

Code Description
200 OK
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.

Get Webhook

var myHeaders = new Headers();
myHeaders.append("Authorization", `Bearer ${bearerToken}`);

var requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/webhook/dab932d2-c490-48de-96a4-f76848241597", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
    "webhookId": "dab932d2-c490-48de-96a4-f76848241597",
    "type": "contact",
    "targetUrl": "https://hooks.zapier.com/hooks/standard/11043413/21d7b275de264bf9aee14a52de22a17d/",
    "isEnabled": true,
    "failureCount": 0,
    "isZapier": true
}

This endpoint retrieves a specific webhook which will be returned if the user has access to it.

Get Webhook HTTP Request

GET https://api.msgboxx.io/webhook/<webhookId>

Get Webhook URL Parameters

Parameter Description
webhookId The Id of the webhook to retrieve

Get Webhook HTTP Responses

Code Description
200 OK
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.

Update Webhook

var myHeaders = new Headers();
myHeaders.append("content-type", "application/json");

var raw = JSON.stringify({
    "type": "contact",
    "targetUrl": "https://hooks.zapier.com/hooks/standard/11043413/21d7b275de264bf9aee14a52de22a17d/",
    "isEnabled": false
    });

var requestOptions = {
  method: "PUT",
  headers: myHeaders,
  body: raw,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/webhook/dab932d2-c490-48de-96a4-f76848241597", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
    "webhookId": "dab932d2-c490-48de-96a4-f76848241597",
    "type": "contact",
    "targetUrl": "https://hooks.zapier.com/hooks/standard/11043413/21d7b275de264bf9aee14a52de22a17d/",
    "isEnabled": false,
    "failureCount": 0,
    "isZapier": true
}

This endpoint updates a specific webhook if the user has access to it. Only fields you can update are the type, targetUrl, and isEnabled.

Update Webhook HTTP Request

PUT https://api.msgboxx.io/webhook/<webhookId>

Update Webhook URL Parameters

Parameter Description
webhookId The Id of the webhook to retrieve

Update Webhook HTTP Responses

Code Description
200 OK
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.

Create Webhook

var myHeaders = new Headers();
myHeaders.append("content-type", "application/json");

var raw = JSON.stringify({
    "type": "message",
    "targetUrl": "https://webhook.site/6899463c-c692-4610-a138-5ba069f690bc",
    "isEnabled": false
});

var requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/webhook", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns JSON structured like this:

{
    "webhookId": "bafb3dd2-8749-4ebf-91ae-dc1ab18a2cc6",
    "type": "message",
    "targetUrl": "https://webhook.site/6899463c-c692-4610-a138-5ba069f690bc",
    "isEnabled": false,
    "failureCount": 0,
    "isZapier": false
}

This endpoint creates a new webhook in the organisation.

Create Webhook HTTP Request

POST https://api.msgboxx.io/organisation

Create Webhook JSON Body

Parameter Description
webhookId The new id of the webhook created
type The type of the webhook, can be message, contact, inbox, apiaccount
targetUrl The url you wish to be called when the event happens
isEnabled Is the webhook enabled
failureCount The current failure count, will default to 0
isZapier Indicated whether its one created by Zapier or not, read only property.

Create Webhook HTTP Responses

Code Description
201 Created
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.
409 Duplicate Contact attempted - contact mobileNumber must be unique per apiAccount

Delete Webhook

var myHeaders = new Headers();
myHeaders.append("content-type", "application/json");

var requestOptions = {
  method: "DELETE",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://api.msgboxx.io/webhook/bafb3dd2-8749-4ebf-91ae-dc1ab18a2cc6", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

The above command returns an empty body, after deleting the webhook.

Delete Webhook HTTP Request

DELETE https://api.msgboxx.io/webhook/<webhookId>

Delete Webhook HTTP Responses

Code Description
204 No Content
400 Bad request. please supply a valid JWT token
401 Authorization information is missing or invalid.

Errors

The msgboxx API uses the following error codes:

4xx

Error Code Meaning
400 Bad Request – Check your input json
401 Unauthorized – Your API bearer token is invalid or expired
403 Forbidden – The requested resource is not available to you
404 Not Found – The specified resource could not be found
405 Method Not Allowed – You tried to access the wrong method
429 Too Many Requests – You’re requesting too many resources!

5xx

Error Code Meaning
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.