NAV Navbar
JSON

User authentication

In order to successfully use our API, you are required to present a valid user name - or email - and the associated authentication token. While creating the request, you have to provide the following parameters:

Field Details Type
UserName* Your username or email String
AuthenticationToken* Your authentication token. String

SendVoice request

Endpoint: https://api-messaging.movile.com/v1/voice/send

There are three different ways of sending voice messages through our API:

The request you make will have different json parameters depending on which of the ways you are using:

Common to all requests is a list of destination blocks:

DestinationBlock

Destination Block JSON structure:

{
  "destination": "string",
  "correlationId": "string",
  "extraInfo": "string"
}

*field is required

Field Details Type
destination* The destination number (with DDI) to which the message will be sent. String
correlationId Any correlation id that you wish to correlate the message to. String
extraInfo Any extra info set by the user when the email was sent. String

SendVoice request (Text To Speech)

Send Voice request JSON structure (tts):

{
  "ttsMessage": "string",
  "destinations": ["destination_block"],
  "campaignAlias": "string"
}

*field is required

Field Details Type
ttsMessage* The text of this message will be transformed into voice. String
destinations A list of the destination blocks. [DestinationBlock]
campaignAlias Alias of a previously created campaign that you wish to link this messages to String

SendVoice request (Audio Url)

Send Voice request JSON structure (with audio url):

{
  "audioUrl": "string",
  "destinations": ["destination_block"],
  "campaignAlias": "string"
}

*field is required

Field Details Type
audioUrl* Our system will process the audio file in this url and send it. String
destinations A list of the destination blocks. [DestinationBlock]
campaignAlias Alias of a previously created campaign that you wish to link this messages to String

SendVoice request (Audio File)

Send Voice request JSON structure (with audio file):

{
  "audioFile": "audio_file_block",
  "destinations": ["destination_block"],
  "campaignAlias": "string"
}

*field is required

Field Details Type
audioFile* And audio file block with the audio information. AudioFileBlock
destinations A list of the destination blocks. [DestinationBlock]
campaignAlias Alias of a previously created campaign that you wish to link this messages to String

AudioFileBlock

Audio File Block JSON structure:

{
  "type": "string",
  "data": "string",
  "name": "string"
}

*field is required

Field Details Type
type* The format of the audio file. E.g. ‘wav’, ‘mp3’. string
data* An audio file encoded as a Base64 string. string
name* The name of the audio file to be shown on the reports. string

SendVoice Response

Send Voice response JSON Structure:

{
  "id": "string",
  "destinations": ["destination_response_block"]
}

The response body will contain a JSON object with tracking information regarding the voice request:

Field Details Type
id UUID generated for this email request. String
destinations A list of destination response blocks. DestinationResponseBlock

DestinationResponseBlock

Destination Block response JSON Structure:

{
  "id": "string",
  "destination": "string",
  "correlationId": "string",
  "extraInfo": "string"
}

A destination response bock is just the same as a DestinationBlock plus the generated id for that message.

Field Details Type
id UUID generated for this destination request. String
destination The destination number (with DDI) to which the message will be sent. String
correlationId Any correlation id that was sent to be correlated to the message. String
extraInfo Any extra info set by the user when the email was sent. String

SearchVoiceStatus request

Search Voice status request JSON Structure:

{
  "ids": ["string"],
  "correlationIds": ["string"],
  "startDate": "string",
  "endDate": "string"
}

Recovers information regarding a previously sent voice messages, given their ids, correlationIds and an interval date.

Field Details Type
ids* UUID generated for the voice messages. [String]
correlationIds List of correlation ids of the messages being searched for. [String]
startDate Start date for search interval. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO String
endDate End date to search interval. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO String

ListVoiceStatus request

Search Voice status request JSON Structure:

{
  "ids": ["string"],
  "correlationIds": ["string"],
}

Endpoint: https://api-messaging.movile.com/v1/voice/status/list

Recovers information regarding previously sent voice messages, given its user and authentication token. This method return all voice messages that have not been previously returned by a ListVoiceStatus request. It is a convenient method of returning all voice messages whose statuses were received after the last time you checked.

Field Details Type
ids* UUID generated for the voice messages. [String]
correlationIds List of correlation ids of the messages being searched for. [String]

ListVoiceStatus and SearchVoiceStatus response

Search and List Voice Status response JSON structure:

[{
  "destination": "destination_response_body",
  "createdAt": "long",
  "createdDate": "string",
  "sent": "boolean",
  "sentStatusCode": "integer",
  "sentStatus": "string",
  "sentAt": "long",
  "sentDate": "string",
  "answered": "boolean",
  "answeredAt": "long",
  "answeredDate": "string",
  "hungUpAt": "long",
  "hungUpDate": "string",
  "campaignId": "long",
  "campaignAlias": "string"
}]
Field Details Type
destination Destination response block for this destination entry. DestinationResponseBlock
createdAt When the voice message was created. It is an Epoch Date. Long
createdDate When the voice message was created. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO String
sent Flag indicating if the voice message was sent. Boolean
sentStatusCode Sent status code. Check Sent Status Codes for more information. Long
sentStatus Sent status. String
sentAt When the voice message was sent. It is an Epoch Date. Long
sentDate When the voice message was sent.Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO String
answered Flag indicating if the voice message was answered by the destination. Boolean
answeredAt When the voice message was answered by the destination. It is an Epoch Date. Long
answeredDate When the voice message was answered by the destination. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO String
hungUpAt When the voice call was hung up. It is an Epoch Date. Long
hungUpDate When the voice call was hung up. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO String
campaignId Campaign identifier. Long
campaignAlias Campaign name. String

Status Codes

Sent Status Codes

A sent status code represents the status of a message passing through our system and being sent to the carrier.

Success codes

Code Code Name Description
2 SENT_SUCCESS Sent to Movile successfully

Error codes

Code Code Name Description
202 INVALID_DESTINATION_NUMBER Destination number is invalid
206 INVALID_MESSAGE_LENGTH Message text was empty
209 INVALID_CONTENT Error generating audio
401 AUTHENTICATION_ERROR Invalid username/authentication token combination

Movile error codes

Code Code Name Description
301 INTERNAL_ERROR Movile internal error

Carrier error codes

Code Code Name Description
102 CARRIER_COMMUNICATION_ERROR There was a problem communicating with the carrier servers.
103 REJECTED_BY_CARRIER Voice message accepted but has not delivered the e-mail.