diff --git a/API-Protocol.md b/API-Protocol.md index 0ccaa9a..20b5a84 100644 --- a/API-Protocol.md +++ b/API-Protocol.md @@ -217,15 +217,16 @@ Authorization: Basic {basic_auth} ## Submitting a message ``` -POST /v1/messages/ +PUT /v1/messages/{destination_number} Authorization Basic {basic_auth} { + relay: "{relay}", messages: [{ type: {type}, - destination: "{destination_number}", + destinationDeviceId: {destination_device_id}, + destinationRegistrationId: {destination_registration_id}, body: "{base64_encoded_message_body}", // Encrypted PushMessageContent - relay: "{relay}", 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. `body` is the Base64 encoded (without padding) and encrypted `PushMessageContent` (above). 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. **Returns**: 1. `401` invalid authentication credentials. +1. `409` mismatched devices. +1. `410` stale devices. 1. `413` rate limit exceeded. 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}], - "failure" : [{destination_number},...,{destination_number}] + missingDevices: [{missing_device_id}, {another_missing_device_id}, ...], + 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; -int TYPE_MESSAGE_PREKEY_BUNDLE = 3; +{ + staleDevices: [{stale_device_id}, ...] +} ``` ## Receiving a message