Protocol Message Send

Messages

Send

The client is responsible for deciding which contacts (at which organizations) should receive a message - and for indicating the wished visibility of the recipient. The actual recipient visibility may be lower with some messaging protocols. For instance, email enables everyone to see the full distribution list (except for, of course, bcc recipients), whereas SMS does not have a recipient list at all.

The server maps a contact at an organization to a number of actual delivery addresses (using the messaging_addresses table). An actual delivery address will only appear once in a message delivery (with the highest of the selected visibilities for that address).

POST /message/send

{
    "callee" : {"name"      : "Callee name",
                "company"   : "Callee company",
                "cellphone" : "4000000", 
                "phone": "5599333"},
    "message": "Actual message body",
    "flags" : ["urgent"],
    "context": {
        "contact": {
            "id": 1,
            "name": "Thomas Løcke"
        },
        "reception": {
            "id": 1,
            "name": "AdaHeads K/S"
        }
    },
    "to": [
        {
            "contact": {
                "id": 1,
                "name": "Thomas Løcke"
            },
            "reception": {
                "id": 1,
                "name": "AdaHeads K/S"
            },
            "role": "to"
        }
    ],
    "cc": [
        {
            "contact": {
                "id": 2,
                "name": "Trine Løcke"
            },
            "reception": {
                "id": 1,
                "name": "AdaHeads K/S"
            },
            "role": "cc"
        }
    ],
    "bcc": [
        {
            "contact": {
                "id": 3,
                "name": "Steen Løcke"
            },
            "reception": {
                "id": 1,
                "name": "AdaHeads K/S"
            },
            "role": "bcc"
        }
    ]
}

The subject of the message is generated server-side and is both dependant on templates and transport types (email, sms).

The callee object contains optional information, which - if omitted - will be filled out with default information by the server.

The flags are arbitrary information which will be stored directly as-is (JSON map) in the database. It is up to the individual templates whether to use the information or not.

Every recipient is fully dereferenced (contact name, reception name) by the client and stored as-sent in the database.

Sends <message> to the listed contacts using the selected visibilities ("to", "cc" or "bcc").

Condition: Success. The message was sent.

HTTP status: 200 OK

An empty object is returned.

Condition: Error. <message> too long, missing or invalid.

HTTP 400 Bad Request

{
  "status":      "bad request",
  "description": "passed message argument is too long, missing or invalid"
}

Condition: Error. No contacts selected.

HTTP 400 Bad Request

{
  "status":      "bad request",
  "description": "no contacts selected"
}

Condition: Error. <contact_id>@<organization_id> does not exist.

HTTP 404 Not Found

{
  "status":      "not found",
  "description": "one of the passed contacts could not be found in the database"
}

Condition: Error. No messaging addresses selected.

HTTP 404 Not Found

{
  "status":      "not found",
  "description": "none of the passed contacts have an enabled messaging address in the database"
}