Conversations connect a client and a DJ, or a DJ and a person who wrote to the DJ's DJfindr email address. Messages in a conversation carry a sequence number, so an application can keep up by polling for what follows the last message it has.
Listing conversations
GET /me/conversations lists the person's conversations, pinned first and then most recent, each with its unread count and last message.
| Parameter | Description |
|---|---|
q | Searches message text, the other person's name and the booking's event name. |
channel | chat, or email for a DJ's threads with people who wrote to their DJfindr email address. |
cursor | The next_cursor from the previous response. |
The response is a single object with items, next_cursor and unread_total, the unread count across every conversation.
Reading messages
Every message has a sequence number, seq, that increases by one within its conversation, without gaps.
| Request | Returns |
|---|---|
GET /me/conversations/{id}/messages?after={seq} | Messages after the given sequence number, oldest first. Poll with the last seq you have. |
GET /me/conversations/{id}/messages?before={seq} | Earlier messages, for scrolling back. |
The response contains items and has_more.
Starting a conversation
POST /prod/v1/me/conversations HTTP/1.1
Host: api.djfindr.com
Authorization: Bearer djf_at_...
Idempotency-Key: 3a9d...
Content-Type: application/json
{ "with_dj": "djada" }| Body field | Description |
|---|---|
with_dj | A DJ's id or slug. |
with | Any person's usr_... id. |
proposal_id | Returns that booking's conversation. A booking the DJ has not accepted yet has no conversation of its own: the conversation between the two people is returned, and the booking is linked to it when the DJ accepts. |
A new conversation returns 201. An existing one returns 200 with created: false.
Sending a message
POST /prod/v1/me/conversations/{id}/messages HTTP/1.1
Host: api.djfindr.com
Authorization: Bearer djf_at_...
Idempotency-Key: 6f1c...
Content-Type: application/json
{ "body": "Hi! Are you free on June 5?", "file_ids": ["file_..."] }A DJ replying to an email thread sends an email reply. To mark messages as read, call POST /me/conversations/{id}/read with { "up_to_seq": 42 }.
Screening
Messages are screened before they are stored, as in the DJfindr apps.
| Outcome | Response |
|---|---|
| Refused | 422 with code: "message_blocked". The refusal counts against the account as it would in the apps; three refusals restrict the account. |
| Screening unavailable | 503. Nothing is sent, and the request is safe to retry. |
Attribution
A message sent through your application carries via ({ "app", "verified", "credential" }), which is null for messages sent on DJfindr. DJfindr shows the message as sent via your application's verified domain, or as "via a connected app" when the application has none. Unverified application names are never displayed.
Limits
Connected applications can start 60 conversations and send 60 messages per hour for each person, shared across all of the person's connected applications. Excess requests return 429 with Retry-After.