Replace instances of [resources] or [resource] with actual resource name.

Excerpt

Panel

Table of Contents

maxlevel	2

Anchor

	post-collection

POST

...

messages

Create a [resource]message

Note: Only outgoing messages can be created through the API. Incoming messages are created by data provider modules.

METHOD: POST
ENDPOINT: /api/v2/[resources]messages/
AUTHENTICATED: No

The request body is a JSON representation of the [resource] message being created.

Example request

Panel

POST https://ushv3.dev/api/v2/[resources]messages

Code Block

title	Post Data
language	javascript

{
    "message": "Test creating outgoing",
    "type": "sms",
    "direction": "outgoing",
    "contact_id": "1"
}

Code Block

title	Response
language	javascript

{
    "id": 9,
    "url": "http:\/\/ushv3.dev\/api\/v2\/messages\/9",
    "parent": null,
    "contact": {
        "id": "1",
        "url": "http:\/\/ushv3.dev\/api\/v2\/contacts\/1",
        "user": {
            "id": "1",
            "url": "http:\/\/ushv3.dev\/api\/v2\/users\/1"
        },
        "contact": "123456789",
        "type": "phone",
        "data_provider": "",
        "created": "1970-01-01T00:00:00+00:00"
    },
    "data_feed": null,
    "post": null,
    "data_provider": null,
    "data_provider_message_id": null,
    "title": null,
    "message": "Test creating outgoing",
    "datetime": null,
    "type": "sms",
    "status": "pending",
    "direction": "outgoing",
    "created": "2014-01-17T03:23:43+00:00",
    "allowed_methods": {
        "get": true,
        "post": true,
        "put": true,
        "delete": true
    }
}

Anchor

	get-collection

GET

...

messages

Listing all [resources]messages

METHOD: GET
ENDPOINT: /api/v2/[resources]messages/
AUTHENTICATED: No

Query Parameters

Note with no parameters the messages API defaults to returning messages with direction = incoming and status != archived.

Name	Type	Description
q	Optional	Only [Resources] messages containing this search string will be returned, matched against 'tag' propertytitle' and 'message' properties
type	Optional	Only [resources] messages of this type will be returned: report, revision, comment or alert
direction	Optional	Filter messages based on direction. incoming or outgoing. Default: incoming
status	Optional	Filter messages based on status. Options: pending, pending_poll, archived, received, expired, cancelled, failed, unknown, sent, all. Default: != archived
parent	Optional	Filter by parent message id
contact	Optional	Filter by contact id
data_feed	Optional	Filter by data feed id
data_provider	Optional	Filter by data provider id
post	Optional	Filter by post id
order	Optional	Returned [resources] messages will be sorted in this order: ASC or DESC. Default: DESC
order_by	Optional	Returned [resources] messages will be sorted by this field. Default: created
limit	Optional	Limit number of results returned. Default: 50. Max: 500
offset	Optional	[Resources] messages returned will be offset by this number of results

...

Panel

GET https://ushv3.dev/api/v2/[resources]messages

Code Block

title	Response
language	javascript

{
    "count": 25,
    "total_count": 5,
    "results": [{
        "id": "1",
        "url": "http:\/\/ushv3.dev\/api\/v2\/messages\/1",
        "parent": null,
        "contact": {
            "id": "1",
            "url": "http:\/\/ushv3.dev\/api\/v2\/contacts\/1",
            "user": {
                "id": "1",
                "url": "http:\/\/ushv3.dev\/api\/v2\/users\/1"
            },
            "contact": "123456789",
            "type": "phone",
            "data_provider": "",
            "created": "1970-01-01T00:00:00+00:00"
        },
        "data_feed": null,
        "post": null,
        "data_provider": null,
        "data_provider_message_id": null,
        "title": "abc",
        "message": "A test message",
        "datetime": null,
        "type": "sms",
        "status": "received",
        "direction": "incoming",
        "created": "1970-01-01T00:00:00+00:00",
        "allowed_methods": {
            "get": true,
            "post": true,
            "put": true,
            "delete": true
        }
    }, {
        "id": "2",
        "url": "http:\/\/ushv3.dev\/api\/v2\/messages\/2",
        "parent": null,
        "contact": {
            "id": "3",
            "url": "http:\/\/ushv3.dev\/api\/v2\/contacts\/3",
            "user": null,
            "contact": "773456789",
            "type": "phone",
            "data_provider": "",
            "created": "1970-01-01T00:00:00+00:00"
        },
        "data_feed": null,
        "post": null,
        "data_provider": null,
        "data_provider_message_id": null,
        "title": "",
        "message": "Another test message",
        "datetime": null,
        "type": "sms",
        "status": "received",
        "direction": "incoming",
        "created": "1970-01-01T00:00:00+00:00",
        "allowed_methods": {
            "get": true,
            "post": true,
            "put": true,
            "delete": true
        }
    }, {
        "id": "3",
        "url": "http:\/\/ushv3.dev\/api\/v2\/messages\/3",
        "parent": null,
        "contact": {
            "id": "2",
            "url": "http:\/\/ushv3.dev\/api\/v2\/contacts\/2",
            "user": null,
            "contact": "somejunkemail@v3.ushahidi.com",
            "type": "email",
            "data_provider": "",
            "created": "1970-01-01T00:00:00+00:00"
        },
        "data_feed": null,
        "post": null,
        "data_provider": null,
        "data_provider_message_id": null,
        "title": "Test email",
        "message": "test email body abc",
        "datetime": "2013-01-02T07:07:00+00:00",
        "type": "email",
        "status": "received",
        "direction": "incoming",
        "created": "1970-01-01T00:00:00+00:00",
        "allowed_methods": {
            "get": true,
            "post": true,
            "put": true,
            "delete": true
        }
    }, {
        "id": "4",
        "url": "http:\/\/ushv3.dev\/api\/v2\/messages\/4",
        "parent": null,
        "contact": {
            "id": "3",
            "url": "http:\/\/ushv3.dev\/api\/v2\/contacts\/3",
            "user": null,
            "contact": "773456789",
            "type": "phone",
            "data_provider": "",
            "created": "1970-01-01T00:00:00+00:00"
        },
        "data_feed": {
            "id": "1",
            "url": "http:\/\/ushv3.dev\/api\/v2\/datafeeds\/1"
        },
        "post": {
            "id": "110",
            "url": "http:\/\/ushv3.dev\/api\/v2\/posts\/110"
        },
        "data_provider": null,
        "data_provider_message_id": null,
        "title": "",
        "message": "Another message with a post",
        "datetime": null,
        "type": "sms",
        "status": "received",
        "direction": "incoming",
        "created": "1970-01-01T00:00:00+00:00",
        "allowed_methods": {
            "get": true,
            "post": true,
            "put": true,
            "delete": true
        }
    }, {
        "id": "5",
        "url": "http:\/\/ushv3.dev\/api\/v2\/messages\/5",
        "parent": null,
        "contact": {
            "id": "1",
            "url": "http:\/\/ushv3.dev\/api\/v2\/contacts\/1",
            "user": {
                "id": "1",
                "url": "http:\/\/ushv3.dev\/api\/v2\/users\/1"
            },
            "contact": "123456789",
            "type": "phone",
            "data_provider": "",
            "created": "1970-01-01T00:00:00+00:00"
        },
        "data_feed": null,
        "post": null,
        "data_provider": "smssync",
        "data_provider_message_id": null,
        "title": "",
        "message": "A test message with provider",
        "datetime": null,
        "type": "sms",
        "status": "received",
        "direction": "incoming",
        "created": "1970-01-01T00:00:00+00:00",
        "allowed_methods": {
            "get": true,
            "post": true,
            "put": true,
            "delete": true
        }
    }],
    "limit": 50,
    "offset": 0,
    "order": "ASCDESC",
    "orderby": "created",
    "curr": "httpshttp:\/\/ushv3.dev\/api\/v2\/[resources]/messages?limit=50&offset=0",
    "next": "httpshttp:\/\/ushv3.dev\/api\/v2\/[resources]/messages?limit=50&offset=50",
    "prev": "httpshttp:\/\/ushv3.dev\/api\/v2\/[resources]/messages?limit=50&offset=0"
}

Search Example

Panel

GET https://ushv3.dev/api/v2/[resources]messages?q=Davidabc

Code Block

title	Response
language	javascript

{
    "count": 12,
    "total_count": 2,
    "results": [{
        "id": "1",
        "url": "http:\/\/ushv3.dev\/api\/v2\/messages\/1",
        "parent": null,
        "contact": {
            "id": "1",
            "url": "http:\/\/ushv3.dev\/api\/v2\/contacts\/1",
            "user": {
                "id": "1",
                "url": "http:\/\/ushv3.dev\/api\/v2\/users\/1"
            },
            "contact": "123456789",
            "type": "phone",
            "data_provider": "",
            "created": "1970-01-01T00:00:00+00:00"
        },
        "data_feed": null,
        "post": null,
        "data_provider": null,
        "data_provider_message_id": null,
        "title": "abc",
        "message": "A test message",
        "datetime": null,
        "type": "sms",
        "status": "received",
        "direction": "incoming",
        "created": "1970-01-01T00:00:00+00:00",
        "allowed_methods": {
            "get": true,
            "post": true,
            "put": true,
            "delete": true
        }
    }, {
        "id": "3",
        "url": "http:\/\/ushv3.dev\/api\/v2\/messages\/3",
        "parent": null,
        "contact": {
            "id": "2",
            "url": "http:\/\/ushv3.dev\/api\/v2\/contacts\/2",
            "user": null,
            "contact": "somejunkemail@v3.ushahidi.com",
            "type": "email",
            "data_provider": "",
            "created": "1970-01-01T00:00:00+00:00"
        },
        "data_feed": null,
        "post": null,
        "data_provider": null,
        "data_provider_message_id": null,
        "title": "Test email",
        "message": "test email body abc",
        "datetime": "2013-01-02T07:07:00+00:00",
        "type": "email",
        "status": "received",
        "direction": "incoming",
        "created": "1970-01-01T00:00:00+00:00",
        "allowed_methods": {
            "get": true,
            "post": true,
            "put": true,
            "delete": true
        }
    }],
    "limit": 50,
    "offset": 0,
    "order": "ASCDESC",
    "orderby": "created",
    "curr": "httpshttp:\/\/ushv3.dev\/api\/v2\/[resources]/messages?q=Davidabc&limit=50&offset=0",
    "next": "httpshttp:\/\/ushv3.dev\/api\/v2\/[resources]/messages?q=Davidabc&limit=50&offset=50",
    "prev": "httpshttp:\/\/ushv3.dev\/api\/v2\/[resources]/messages?q=Davidabc&limit=50&offset=0"
}

Anchor

	get-id

GET

...

messages/:id

Get a single [resource]single message

METHOD: GET
ENDPOINT: /api/v2/[resources]messages/:id
AUTHENTICATED: Yes

Query Parameters

Name	Type	Description
id	Required	The numerical id of the [resource] message being updated.

Example Request

Panel

GET http://ushv3.dev/api/v2/[resources]messages/1

Code Block

title	Response
language	javascript

{
	
}
    "id": "1",
    "url": "http:\/\/ushv3.dev\/api\/v2\/messages\/1",
    "parent": null,
    "contact": {
        "id": "1",
        "url": "http:\/\/ushv3.dev\/api\/v2\/contacts\/1",
        "user": {
            "id": "1",
            "url": "http:\/\/ushv3.dev\/api\/v2\/users\/1"
        },
        "contact": "123456789",
        "type": "phone",
        "data_provider": "",
        "created": "1970-01-01T00:00:00+00:00"
    },
    "data_feed": null,
    "post": null,
    "data_provider": null,
    "data_provider_message_id": null,
    "title": "abc",
    "message": "A test message",
    "datetime": null,
    "type": "sms",
    "status": "received",
    "direction": "incoming",
    "created": "1970-01-01T00:00:00+00:00",
    "allowed_methods": {
        "get": true,
        "post": true,
        "put": true,
        "delete": true
    }
}

Anchor

	put-id

PUT

...

messages/:id

Update a [resource]a message

METHOD: PUT
ENDPOINT: /api/v2/[resources]messages/:id
AUTHENTICATED: Yes

Messages updates are subject to special rules depending on if they are incoming or outgoing

Incoming messages only allow updates to 'status'. The message itself cannot be edited
Outgoing messages allow most values to be updated as normal

Query Parameters

Name	Type	Description
id	Required	The numerical id of the [resource] message being updated.

Example Request

Panel

Archive message, and try to edit the message text.. In this case the message is status is changed but other changes are ignored.

PUT http://ushv3.dev/api/v2/[resources]messages/1

Code Block

title	Post Data
language	javascript

{
	
    "message": "Overwrite message",
    "status": "archived"
}

Code Block

title	Response
language	javascript

{
	
}
    "id": "1",
    "url": "http:\/\/ushv3.dev\/api\/v2\/messages\/1",
    "parent": null,
    "contact": {
        "id": "1",
        "url": "http:\/\/ushv3.dev\/api\/v2\/contacts\/1",
        "user": {
            "id": "1",
            "url": "http:\/\/ushv3.dev\/api\/v2\/users\/1"
        },
        "contact": "123456789",
        "type": "phone",
        "data_provider": "",
        "created": "1970-01-01T00:00:00+00:00"
    },
    "data_feed": null,
    "post": null,
    "data_provider": null,
    "data_provider_message_id": null,
    "title": "abc",
    "message": "A test message",
    "datetime": null,
    "type": "sms",
    "status": "archived",
    "direction": "incoming",
    "created": "1970-01-01T00:00:00+00:00",
    "allowed_methods": {
        "get": true,
        "post": true,
        "put": true,
        "delete": true
    }
}

Anchor

	delete-id

DELETE

...

messages/:id

Deleting a [resource]a message

METHOD: DELETE
ENDPOINT: /api/v2/[resources]messages/:id AUTHENTICATED: YES

Query Parameters

Name	Type	Description
id	Required	The numerical id of the [resource] being deleted.

Example request

Panel

DELETE /api/v2/[resources]/2

Code Block

title	Response
language	javascript

{
	
}

Messages cannot be deleted through the API.

FOR ARCHIVAL PURPOSES ONLY

Versions Compared

Old Version 1

New Version Current

Key

POST

messages

Example request

GET

messages

Query Parameters

Search Example

GET

messages/:id

Query Parameters

Example Request

PUT

messages/:id

Query Parameters

Example Request

DELETE

messages/:id

Query Parameters

Example request

FOR ARCHIVAL PURPOSES ONLY

Community Wiki … Welcome to the Ushahidi wiki! Our Products Ushahidi Platform v3.x Ushahidi v3.x - Developer Guide Ushahidi 3.x REST API Ushahidi 3.x API Resources Ushahidi 3.x API Messages Resource Page History

Versions Compared

Old Version 1

New Version Current

Key

POST

messages

Example request

GET

messages

Query Parameters

Search Example

GET

messages/:id

Query Parameters

Example Request

PUT

messages/:id

Query Parameters

Example Request

DELETE

messages/:id

Query Parameters

Example request

Community Wiki
…

Welcome to the Ushahidi wiki!
Our Products
Ushahidi Platform v3.x
Ushahidi v3.x - Developer Guide
Ushahidi 3.x REST API
Ushahidi 3.x API Resources
Ushahidi 3.x API Messages Resource

Page History