Server API

What the Namjai server is, how to start it on your own computer, and how a program talks to it.

What the server is for

The Namjai server, the program namjai-server, receives the conversations that the Namjai app captures, keeps every event once, and reads a conversation back in the order it happened. The app sends to it with namjai wp sync and namjai demo send.

Status: the server runs on your own computer, for development. There is no hosted Namjai server yet: the addresses planned for it serve nothing, so do not try to reach them.

The server answers two services. Each has its own page, made from the API contract so it cannot drift from what the server accepts:

Start it on your computer

In the folder of the Namjai code, the first time only:

make setup

Start the local databases the server keeps its data in:

make databases-up

Start the server. It runs until you press Control and C:

make server

The address it listens on is the setting NAMJAI_LISTEN, 127.0.0.1:4710 in .env.example. The app sends to the setting NAMJAI_SERVER, http://127.0.0.1:4710 there. Change both in your own .env to use another port.

How a call travels

The two services speak the Connect protocol over HTTP. A call is a POST to the server's address, then the service's full name, then the call's name:

http://127.0.0.1:4710/namjai.v1.TimelineService/ListConversationEvents

The body is the request message, as JSON with the header Content-Type: application/json, or as protobuf with Content-Type: application/proto. The answer comes back in the same format, with HTTP status 200.

A call that fails answers with another HTTP status and a JSON body that holds a code and a message, such as {"code":"invalid_argument","message":"..."}. The codes this server returns:

CodeHTTP statusWhen
invalid_argument400The request is wrong: a batch with no batch_id, more than 1,000 events, an event whose event_id does not match its identity fields, with no content or no time; a media registration with a bad sha256, event_id, upload_url or size; a timeline request without channel, account or conversation, with a negative page size or a page token this server did not make.
not_found404RegisterMedia names an upload the server does not have.
failed_precondition400RegisterMedia names an upload that is not finished yet.
unavailable503The database or the file store did not answer or refused a write. Sending the same call again is safe.
internal500SendBatch could not encode the batch to keep a copy of it.

An address the server does not know answers 404 page not found as plain text.

Other addresses

Besides the two services, the server answers these:

Method and pathTakesAnswers
GET /healthzNothing.200 and {"blob":"ok","mongo":"ok"} when the database and the file store both answer within 2 seconds; otherwise 503, with the error in place of ok.
POST /uploads/The start of a resumable file upload in the tus 1.0 protocol: headers Tus-Resumable: 1.0.0 and Upload-Length, the file's size, at most 4 GiB.201 and a Location header, the upload's address /uploads/<id>.
PATCH /uploads/<id>The next part of the file's bytes, with Content-Type: application/offset+octet-stream and Upload-Offset, how many bytes the server already has.204 and the new Upload-Offset.
HEAD /uploads/<id>Nothing.The upload's Upload-Offset and Upload-Length, so an interrupted upload goes on where it stopped.

A finished upload is attached to its event with RegisterMedia. The server does not hand uploaded files back: downloads are turned off.

Who may call it

Anyone who can reach the address. The server has no sign-in, no key and no check of which device is calling: every call and upload is accepted from anyone who can connect. The device ID and version a call carries in CollectorInfo are stored with the batch, not checked. That is why it listens on 127.0.0.1, which only this computer can reach. Do not make it listen on an address other computers can reach.

Try it

With the server started as above, in a second Terminal window. Every number and text here is the made-up demo data, with test numbers that start with +999.

Ask whether it is healthy

curl -s -i http://127.0.0.1:4710/healthz
Terminal
HTTP/1.1 200 OK
Content-Type: application/json
Date: Tue, 17 Nov 2026 03:14:35 GMT
Content-Length: 27

{"blob":"ok","mongo":"ok"}

Send the demo conversation

dist/namjai demo send --seed 7
Terminal
batch_id=20476433-9531-886c-81dd-946d39d18e58
conversation_id=99900000142@s.whatsapp.net
call_conversation_id=+99900000142
events_sent=12
events_new=12
events_duplicate=0
media_uploaded=3
media_new=3
media_in_raw_store=3
bytes_uploaded=256167
outbox_left=0

make demo seed=7 builds the app and runs the same command. Sending it again creates nothing new: every event counts as a duplicate.

Read the conversation back

This asks for one event, "pageSize": 1, to keep the answer short. Without it the answer holds up to 100 events.

curl -s -X POST http://127.0.0.1:4710/namjai.v1.TimelineService/ListConversationEvents -H 'Content-Type: application/json' -d '{"channel": "CHANNEL_WHATSAPP", "account": "+99900000101", "conversationId": "99900000142@s.whatsapp.net", "pageSize": 1}'
Terminal
{"events":[{"event":{"eventId":"ev1_4a68f846342f698aaed7b889ab1022fb", "channel":"CHANNEL_WHATSAPP", "account":"+99900000101", "conversationId":"99900000142@s.whatsapp.net", "direction":"DIRECTION_INBOUND", "sourceMessageId":"3AC9F60BEF60E70A5D0D", "occurredAtUnixMs":"1795343797003", "capturedAtUnixMs":"1795343798771", "sourceSequence":"47672", "sender":"+99900000142", "language":"he", "text":{"text":"שלום, ראיתי את המודעה על הדירה ברחוב הדוגמה 12. היא עדיין פנויה?"}}, "receivedAtUnixMs":"1794885275805"}], "nextPageToken":"eyJvIjox..."}

The numbers that count milliseconds come back as strings, because they are 64-bit. To read the next page, send the same request with "pageToken" set to the whole nextPageToken. It is shortened above to its first characters; the real one was 96 characters long in this run.

A call that fails

An empty request names no conversation:

curl -s -i -X POST http://127.0.0.1:4710/namjai.v1.TimelineService/ListConversationEvents -H 'Content-Type: application/json' -d '{}'
Terminal
HTTP/1.1 400 Bad Request
Accept-Encoding: gzip
Content-Type: application/json
Date: Tue, 17 Nov 2026 03:14:35 GMT
Content-Length: 93

{"code":"invalid_argument","message":"channel, account and conversation_id are all required"}