Calling the Enterprise Communications API

End Points

The following endpoints (URLs) are available for the Enterprise Communications API for HTTP POSTing to.

๐Ÿ“˜

Which method to use?

Use the batch submission if you have more than one message to send at a time, otherwise use the single submission.

๐Ÿšง

We will only accept connections using TLS 1.1 or above

For security reasons we do not accept SSL connections negotiated using TLS 1.0 anymore. Almost all OS's support TLS 1.1 or higher, and we recommend using TLS 1.2 if supported. This is usually done automatically for you, but on versions of .Net prior to 4.6 TLS 1.2 is supported but is not the default protocol, and needs to be set explicitly.

ServicePointManager.SecurityProtocol = (SecurityProtocolType)3072 | (SecurityProtocolType)768;

See this article for more information.

Single Message Submission

The endpoint for the web service is: https://api.comapi.com/apispaces/apiSpaceId/messages

Send a single message request object using JSON e.g.

{
  "body": "Sending messages is easy!",
  "to": {
    "phoneNumber": "447123123123"
  },
  "rules": [
    "sms"
  ]
}

You can find more details about the end point here, but please read this section first so that you are familiar with how the API works.

Batch Message Submission

The endpoint for the web service is: https://api.comapi.com/apispaces/apiSpaceId/messages/batch

Send a batch of message request objects using a JSON array e.g.

[
  {
    "body": "This is message 1",
    "to": {
      "profileId": "[email protected]",
      "phoneNumber": "447123123123"
    },
    "rules": [
      "fbMessenger",
      "sms"
    ]
  },
  {
    "body": "This is message 2",
    "to": {
      "profileId": "[email protected]",
      "phoneNumber": "447234234234"
    },
    "rules": [
      "fbMessenger",
      "sms"
    ]
  }
]

You can find more details about the end point here, but please read this section first so that you are familiar with how the API works.

Content Type

The content type for the HTTP requests should be set to application/json using the Content-Type HTTP header:

Content-Type: application/json

Security

Secure communications

The Enterprise Communications API is only accessible via secure communications using 2048 bit TLS encryption.

Granular authorisation

The authorisation to invoke methods on the API is provided by claims in JWT access tokens that can be created by sufficiently privileged users in the Portal. Tokens may be revoked at any time, and can be assigned permissions individually to allow least privilege best practices to be easily implemented.

See our Quick Start guide for more details on how to setup a security token.

Authorising web service calls

To use your access token to authorise calls to our web services you should ensure that your token is included in the Authorization HTTP header as a Bearer for example:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI3NjYzZGU4OC02MTRlLTQ1NTYtYmNiYi1mMDJlZjk4OWFlN2UiLCJpc3MiOiJodHRwczovL2FwaS5jb21hcGkuY29tL2FjY2Vzc3Rva2VucyIsImF1ZCI6Imh0dHBzOi8vYXBpLmNvbWFwaS5jb20iLCJhY2NvdW50SWQiOjM5Njk0LCJhcGlTcGFjZUlkIjoiNTMzNjQxOTgtM2YzZi00NzIzLWFiOGYtNzA2ODBjMTExM2IxIiwicGVybWlzc2lvbnMiOlsiY29udjpycHUiLCJjb252OnJwciIsImNvbnY6cmEiLCJjb252OndwdSIsImNvbnY6d3ByIiwiY29udjpkcHUiLCJjb252OmRwciIsImNvbnY6ZGEiLCJjb252bXNnOnIiLCJjb252bcgHtyIoLCJjaGFuOnIiLCJjaGFuOnciLCJjaGFuOmQiLCJwcm9mOnJhIiwicHJvZjpybyIsInByb2Y6d2EiLCJwcm9mOndvIiwicHJvZjpkYSIsInByb2Y6ZG8iLCJtc2c6c21zOnMiLCJtc2c6ZmJtc2c6cyIsIm1zZzphcHBtc2c6cyIsIm1zZzpjdXN0b206cyIsIm1zZzpyIiwiYXBpczpybyJdLCJzdWIiOiI3NjYzZGU4OC02MTRlLTQ1NTYtYmNiYi1mMDJlZjk4OWFlN2UiLCJwcm9maWxlSWQiOiJDb21hcGlfU3VwcG9ydCIsIm5hbWUiOiJNZXlhLVN1cHBvcnQiLCJpYXQiOjE0ODcxODUxNzB9.vRx3nQyeg66eZLeKZ03R1Npcayul_XdipvoObBF_M2I
POST /apispaces/53364198-3f3f-4723-ab8f-70680c1113b1/messages HTTP/1.1
Host: api.comapi.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI3NjYzZGU4OC02MTRlLTQ1NTYtYmNiYi1mMDJlZjk4OWFlN2UiLCJpc3MiOiJodHRwczovL2FwaS5jb21hcGkuY29tL2FjY2Vzc3Rva2VucyIsImF1ZCI6Imh0dHBzOi8vYXBpLmNvbWFwaS5jb20iLCJhY2NvdW50SWQiOjM5Njk0LCJhcGlTcGFjZUlkIjoiNTMzNjQxOTgtM2YzZi00NzIzLWFiOGYtNzA2ODBjMTExM2IxIiwicGVybWlzc2lvbnMiOlsiY29udjpycHUiLCJjb252OnJwciIsImNvbnY6cmEiLCJjb252OndwdSIsImNvbnY6d3ByIiwiY29udjpkcHUiLCJjb252OmRwciIsImNvbnY6ZGEiLCJjb252bXNnOnIiLCJjb252bcgHtyIoLCJjaGFuOnIiLCJjaGFuOnciLCJjaGFuOmQiLCJwcm9mOnJhIiwicHJvZjpybyIsInByb2Y6d2EiLCJwcm9mOndvIiwicHJvZjpkYSIsInByb2Y6ZG8iLCJtc2c6c21zOnMiLCJtc2c6ZmJtc2c6cyIsIm1zZzphcHBtc2c6cyIsIm1zZzpjdXN0b206cyIsIm1zZzpyIiwiYXBpczpybyJdLCJzdWIiOiI3NjYzZGU4OC02MTRlLTQ1NTYtYmNiYi1mMDJlZjk4OWFlN2UiLCJwcm9maWxlSWQiOiJDb21hcGlfU3VwcG9ydCIsIm5hbWUiOiJNZXlhLVN1cHBvcnQiLCJpYXQiOjE0ODcxODUxNzB9.vRx3nQyeg66eZLeKZ03R1Npcayul_XdipvoObBF_M2I
Content-Type: application/json

๐Ÿ“˜

Need a access token?

See our quick start guide for a guide to creating access tokens in the portal