Convert a time between time zones
well_convert_timeCall this for any time that is stated in another time zone than the one you will write it in ("3pm New York time", "10am in Tokyo", "what time is that for me?"): never work out an offset or a daylight-saving change yourself, because Well does the calculation and your own arithmetic is wrong around the clock changes.
Pass local_time as the wall-clock date and time, YYYY-MM-DDTHH:mm with no offset and no Z, and from_timezone as the IANA zone that clock is in. Leave to_timezone out to convert into the user's own time zone; pass it to convert into another zone.
Returns instant_utc, from and to. Each of from and to holds the timezone, the local_time with its UTC offset on that day, and the utc_offset. Use to.local_time as the start of a calendar event: its offset is already right.
A clock time that does not exist (the hour skipped when clocks go forward) moves forward by the gap, and one that happens twice (the hour repeated when clocks go back) is the first of the two. When that happens the result carries adjustment ("shifted_forward" or "earlier_of_two") and note, a sentence for the user: tell the user what it says, in the language of the conversation, and use the returned time. On a normal time adjustment and note are absent.
On success false, error_reason says why and error is a plain sentence. "unknown_timezone": the zone name is not an IANA name. "invalid_time": local_time is not a real date and time. "user_timezone_unknown": no time zone is known for the user, so ask them which one they are in and call again with to_timezone set to their answer. In a scheduled run no one can answer: report that the time zone is unknown and write no timed event. Never guess a zone and never fall back to UTC.
When the token authorizes one workspace, call this directly — no workspace call is needed first. When it authorizes several, this read will not guess which one you mean: pass workspace_id on the call.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| local_time | Yes | The wall-clock date and time to convert, YYYY-MM-DDTHH:mm, as read on a clock in from_timezone. | |
| to_timezone | No | The IANA time zone to show the time in. Leave out for the user's own time zone. | |
| workspace_id | No | Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which. | |
| from_timezone | Yes | The IANA time zone local_time is read in, such as America/New_York. | |
| conversation_id | No | The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation. | |
| workspace_scope | No | Restrict this call to the family: the token's primary workspace plus the company workspaces under it that you are a member of. Unrelated authorized workspaces drop out of the read; row reads merge across the family, while a per-workspace figure still reports exactly one workspace. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ||
| from | No | ||
| note | No | ||
| error | No | ||
| success | Yes | ||
| adjustment | No | ||
| instant_utc | No | ||
| error_reason | No | ||
| conversation_id | No | The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation. | |
| newly_connected | No | Tools that connected to this workspace since the last result and that no session was told about yet, oldest first. Present only when at least one tool is new. The connected-line rule says when to tell an entry; when it does, one line per entry, in the person's language: "<name> is connected.". Never fold several entries into one sentence. Each entry comes back once, on one result only: never repeat its line later. | |
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. | |
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| conversation_id_source | No | Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened. |