MirrorMirror
/
Signal-Server
mirror of https://github.com/signalapp/Signal-Server.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updated API Protocol (markdown)

Moxie Marlinspike 2014-04-02 12:07:09 -07:00
parent df3fdf38d1
commit 2bed362f99
1 changed files with 22 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
API-Protocol.md

@ -217,15 +217,16 @@ Authorization: Basic {basic_auth}
## Submitting a message ## Submitting a message
``` ```
POST /v1/messages/ PUT /v1/messages/{destination_number}
Authorization Basic {basic_auth} Authorization Basic {basic_auth}
{ {
relay: "{relay}",
messages: [{ messages: [{
type: {type}, type: {type},
destination: "{destination_number}", destinationDeviceId: {destination_device_id},
destinationRegistrationId: {destination_registration_id},
body: "{base64_encoded_message_body}", // Encrypted PushMessageContent body: "{base64_encoded_message_body}", // Encrypted PushMessageContent
relay: "{relay}",
timestamp: "{time_sent_millis_since_epoc}" timestamp: "{time_sent_millis_since_epoc}"
}, },
..., ...,
@ -233,32 +234,41 @@ Authorization Basic {basic_auth}
} }
``` ```
1. `type` is the type of message. Supported types are enumerated below.
1. `destination_number` is the PSTN number of the message recipient. 1. `destination_number` is the PSTN number of the message recipient.
1. `body` is the Base64 encoded (without padding) and encrypted `PushMessageContent` (above).
1. `relay` (optional) is the relay the message recipient is registered with. 1. `relay` (optional) is the relay the message recipient is registered with.
1. `type` is the type of message. Supported types are enumerated below.
1. `destination_device_id` is the target device the message corresponds to for the `destination_number`.
1. `body` is the Base64 encoded (without padding) and encrypted `PushMessageContent` (above).
1. `timestamp_sent_millis_since_epoch` is the timestamp of the message in millis since the epoch. 1. `timestamp_sent_millis_since_epoch` is the timestamp of the message in millis since the epoch.
**Returns**: **Returns**:
1. `401` invalid authentication credentials. 1. `401` invalid authentication credentials.
1. `409` mismatched devices.
1. `410` stale devices.
1. `413` rate limit exceeded. 1. `413` rate limit exceeded.
1. `415` badly formatted JSON. 1. `415` badly formatted JSON.
1. `200` request succeeded. The structure below is returned. 1. `200` request succeeded.
**409 Mismatched Devices**:
This return code indicates that the devices in `messages` do not match the registered devices for `destination_number`. The response body indicates the mismatch:
``` ```
{ {
"success" : [{destination_number}, {destination_number}, ..., {destination_number}], missingDevices: [{missing_device_id}, {another_missing_device_id}, ...],
"failure" : [{destination_number},...,{destination_number}] extraDevices: [{device_id_doesnt_exist}, ...]
} }
``` ```
Supported types: **410 Stale Devices**:
This return code indicates that a target device has re-installed and the requesting client is sending a message for a stale session. The response body indicates which devices are effected:
``` ```
int TYPE_MESSAGE_PLAINTEXT = 0; {
int TYPE_MESSAGE_CIPHERTEXT = 1; staleDevices: [{stale_device_id}, ...]
int TYPE_MESSAGE_PREKEY_BUNDLE = 3; }
``` ```
## Receiving a message ## Receiving a message