Skip to main content

Talk to the node

Being connected to the node and having our service registered there is one thing. But what's next? How to build messages in our services, so they can be passed to the node and understood correctly?

Create job

To create a message that is understandable by the node, we need to create a job. Job is created using dedicated function called jobCreation (or job_creation in Python). This function generates a ShinkaiMessage that acknowledges the job must be created.

Having job creation message, we need to send it to create_job endpoint on the node. As the result, we receive unique jobId which we can later use to talk to the node regarding specific context/conversation.

It's important at this stage to identify what kind of agent we want the job to use. More on that here: For detailed information on the types of agents available and how to configure them for your specific needs, please refer to our comprehensive guide on Shinkai Agents.

Here's some exemplary code on how to create a job from the external service:

 const job_scope: any = {
local: [],
vector_fs: [],

const jobCreationMessage = await ShinkaiMessageBuilder.jobCreation(
// send jobCreationMessage in the payload to `v1/create_job`
// as a result we receive job_id::id

Create message

Having unique jobId in place, we can now proceed to posting specific message to our node. Again, we're going to use dedicated jobMessage function and then send the result of this function to dedicated endpoint exposed by the Shinkai Node itself.

const jobMessage = await ShinkaiMessageBuilder.jobMessage(
filesInbox ?? "",

// send jobMessage in the payload to `/v1/job_message`

When message is sent, the node proceeds with processing. At this point we did all the steps to send the message to the node and make the node act upon it. Once the node resolves the message it will share the response, however it won't be done as a response to the job_message endpoint.

Check out how to read job messages responses here: To read job messages responses, refer to the detailed guide in Receiving Node Responses.

Context of the conversation

What about the context of the conversation? It was said before that being in the same job, means that the whole history of the conversation is considered while talking with the AI. This is true. How to ensure that we are in the same context of the specific conversation we are interested about?

In order to ensure that we are sending messages to the specific conversation with dedicated context, we need to remember one simple rule. Job ID allows us to identify the conversation. So, whenever we want to send the message to the already existing conversation, and our message assumes the context is remembered, we need to include that conversation jobId inside our message. That said, we need to perform the following steps:

  1. Remember jobId of the conversation which we want to continue
  2. While creating new message, we must provide the jobId of the remembered conversation to the jobMessage function payload.

Having those 2 pieces in place, we can acknowledge what is that we continue the same conversation inside one inbox.

Example Imagine creating a message on Slack on the channel. A bot mentioned in the conversation sends your message to the node and replies in the thread. Then, you want to continue asking about the same subject, so you ask another question in the thread mentioning the bot again. In order to be able to remember what was previous question about, the node needs to know the jobId of the initial message. This is done by the bot on the backend side (mapping between main thread and jobId).