Skip to main content
The Wordsmith connector for Workato lets any recipe send work to Wordsmith and use the result in later steps. A recipe can start from any Workato trigger, such as a new contract in your CLM, a procurement request, a ServiceNow ticket or a Salesforce opportunity. It can also start when a Wordsmith task is created or completed.
The connector is not yet in Workato’s community library. Until it is, a Workato admin adds it to your workspace. See Add the connector.

​
Actions and triggers

Each trigger starts the recipe at once: Wordsmith sends every event to the recipe. These instant triggers need instant triggers to be on for your organisation; ask your Wordsmith contact. An instant trigger gives the IDs, status and link of what changed, so add Get a task or Find a review for the full record. New task, Task status changed and Review completed also come in a polling version, which checks every poll interval, 5 minutes by default, and works for every organisation. Narrow Task status changed (polling) with Assignee, Source channel (for example api, for tasks a recipe created) or Tags, and New task (polling) with Agent or Assignee. Ask an agent and the document, review and draft actions keep the recipe waiting while Wordsmith works, which usually takes a few minutes. The document, review and draft actions wait up to about 100 minutes, then fail with the job ID, so Get a job can read the result later. Ask an agent usually answers in a few minutes. The connector checks for the answer every minute or so. Set Wait up to (minutes) for how long to wait; the default is 60. If the agent is still working after that, the step fails with the question ID, so a later Get an answer can read the answer. The step also fails when the agent could not answer, with the agent’s message and a link to the conversation. Use an error monitor in the recipe to handle both. When it succeeds, Status is completed, or filtered when the agent declined the question, with the reason in Decline reason. The answer comes in two forms. Answer is Markdown. Answer (HTML) is the same text formatted for an email body, so use it when you send an email: headings, lists and bold text then show properly.

​
Connect

  1. In Wordsmith, open each agent the recipe should hand tasks to, and add API as an intake on its configuration page. The Agent list in Create a task shows only agents with that intake.
  2. In Workato, add a Wordsmith step to a recipe and create a connection. Choose your Region: Europe or United States.
  3. Under Sign in with, choose Wordsmith account (OAuth), then Connect. Sign in to Wordsmith and approve the access the connector asks for. The connection acts as you, and you can disconnect it in Wordsmith under Settings → App access. For recipes that serve a whole team, connect as a user who can see that team’s work.
  4. Or choose API key: in Wordsmith, open Settings → API keys, create a key, and paste it. The connection acts with the access of the person who created the key. A key limited to some scopes needs me:read, agents:read, sessions:read, sessions:write, files:read, files:write, tasks:read and tasks:write. Add reviews:read and reviews:write for reviews, playbooks:read and blueprints:read for their dropdowns, directory:read for the Assignee dropdown, and webhooks:read and webhooks:write for the instant triggers.

​
Example: review each new contract request

This recipe sends each new request to an agent and posts the answer back.
  1. Start the recipe from your request system’s New record trigger.
  2. If the request has a file, download it with that system’s download action. Add Wordsmith → Upload a file with the file’s contents and name.
  3. Add Wordsmith → Ask an agent:
    • Agent: the agent that handles these requests.
    • Question: the instruction, with the request’s fields inserted. For example: Review this NDA request from <Requester>. Counterparty: <Counterparty>. Deadline: <Deadline>.
    • Files: the File ID from Upload a file.
    • Idempotency key: the request’s record ID plus the step name, so a rerun of the job does not ask twice. Give each Wordsmith step its own key.
  4. Add an IF step: Status equals completed.
  5. Under it, post Answer (HTML) and Conversation link back to the request, or email them to the requester.
  6. Otherwise, send the requester the Decline reason, so a declined request is not lost.
To have a person check the work first, use Create a task instead of step 3. Assign the task to an agent, put the request’s fields in Description, and add the files. Then build a second recipe on Task status changed (polling), filtered to Source channel api, that reads Output files and posts them back.

​
Add the connector

Until the connector is in the community library, a Workato admin adds it to your workspace as a custom connector:
  1. Ask support@wordsmith.ai for the Workato connector. Support sends a share link or the connector’s source code.
  2. Open the share link and install the connector. With the source code instead, create a connector under Tools → Connector SDK and paste the code in.
  3. Release the connector, so recipe builders in the workspace can use it.

​
Limits

  • Ask an agent waits at most as long as Wait up to (minutes). A question that waits on a person’s approval can take days, so use Get an answer to read it later.
  • Files the agent created have two links. Download URL expires 5 minutes after the answer arrives, so download it in the next step, and never email it. Link does not expire, but needs Wordsmith sign-in.
  • Task status changed (polling) starts the recipe once per task and status, even if the task is reopened and completed again. A task completed before the recipe’s start time can start it once if the task changes after that time.
  • New task (polling) reads open tasks in priority order, at most 500 per check. If you are involved in more open tasks than that, a new low-priority task can be missed.
  • Review completed (polling) checks the 150 newest reviews, so an older review that finishes later can be missed. The instant version has no such limit.
  • An instant trigger’s webhook lives as long as the recipe runs. If Wordsmith turns it off, for example because the API key was deleted or the app was disconnected, restart the recipe after reconnecting.
  • Draft a document with a blueprint also takes instructions, background and reference files, and Wordsmith uses them to fill the fields you leave empty. A table field takes a JSON list of rows, each a list of cell texts, such as [["Alpha Ltd", "London"]].
  • Review a document lists in Checks that could not run any check the review could not run. When that list is not empty, the review is partial.
  • Review completed can miss a finished review for now. If a recipe must catch every one, use Review completed (polling).
  • An OAuth connection stays signed in while its recipes run at least once every 90 days. After 90 days without a run, or when your organisation’s own sign-in limit passes, connect again. An API key does not expire this way.