setDocument

Stores a document in a collection, creating it or replacing it in place.

⚠️ This is a full replace, not a merge. Fields you omit are gone. To change one field, read the document first, modify it, and send the whole thing back.

Request

method is "setDocument".

Field	Type	Required	Description
`collection`	String	Yes	The collection to store into. Created implicitly on first write.
`document_id`	String	Yes	The document's id within the collection.
`document`	Object	Yes	The JSON document to store.
`app_id`	String	Optional	The app the document belongs to. Defaults to the bot's own app.
`reference`	String	Optional	Your id for this request. Echoed back in the response.

Response

setDocumentResponse

Field	Type	Returned	Description
`method`	String	Yes	`"setDocumentResponse"`
`collection`	String	Yes	Echoed from the request.
`document_id`	String	Yes	Echoed from the request.
`document`	Object	Yes	The document as stored.
`ack`	Integer	Yes	Rows affected: `1` for an insert, `2` for a replace.
`app_id`	String	Yes	Echoed from the request.
`reference`	String	Optional	Echoed from the request.

SDKs

SDK	Call	Callback
Java	`store.setDocument(api, collection, documentId, document, reference);`	`onDocumentResponse(DocumentResponse response)`
JavaScript	`store.setDocument(api, collection, documentId, document, reference);`	`onDocumentResponse(response)`
Python	`store.set_document(api, collection, document_id, document, reference)`	`on_document_response(self, response)`

Example

Request

json
{
  "method": "setDocument",
  "collection": "orders",
  "document_id": "42",
  "app_id": "90090684293000559",
  "reference": "123456789",
  "document": {
    "status": "shipped",
    "total": 149.5,
    "region": "EG",
    "items": ["sku-1", "sku-7"],
    "created_at": "2026-07-27T10:00:00Z"
  }
}

java
JSONObject document = new JSONObject();
document.put("status", "shipped");
document.put("total", 149.5);
document.put("region", "EG");

DocumentStore.getInstance().setDocument(api, "orders", "42", document, "123456789");

javascript
const store = require('nandbox-bot-api/src/util/DocumentStore')

store.setDocument(api, 'orders', '42', {
  status: 'shipped',
  total: 149.5,
  region: 'EG'
}, '123456789')

python
from nandboxbots.util.DocumentStore import DocumentStore

DocumentStore.get_instance().set_document(
    api,
    "orders",
    "42",
    {"status": "shipped", "total": 149.5, "region": "EG"},
    "123456789",
)

Response

json
{
  "method": "setDocumentResponse",
  "collection": "orders",
  "document_id": "42",
  "app_id": "90090684293000559",
  "reference": "123456789",
  "ack": 1,
  "document": {
    "status": "shipped",
    "total": 149.5,
    "region": "EG",
    "items": ["sku-1", "sku-7"],
    "created_at": "2026-07-27T10:00:00Z"
  }
}