Build and test Custom API operations

Technical guide for the person configuring your integration. An API is a way for two systems to exchange requests and information. An endpoint is one operation in that connection, such as looking up a delivery. Start with connecting another system if you need the connection and sign-in settings first.

How it works

A connection holds a supplier’s base address, authentication and shared headers. Each endpoint holds one request, its inputs, instructions and the response fields you allow the bot to receive. Configuring an endpoint does not mean it will be used for every conversation.

New endpoints start disabled. For normal chat use, both the endpoint and its connection must be Enabled. Testing is separate: Run test call sends a real request even while the draft is disabled.

Use Performs a real action for anything that changes the other system. Then choose Ask a teammate before each call separately. Approval is off for endpoints created from scratch; imported presets and templates can carry it on. Existing write endpoints kept it on. The HTTP method does not decide this: a supplier may use POST for a lookup as well as for a change.

An authorized connected agent can raise or lower customer-verification and user-source requirements directly, with the same permissions and validation as your app editor. It can also edit methods and real-action classification while an endpoint is on. Secret entry and real tests keep their existing in-app steps; editing does not test or send anything. See connection editing for secret removal and endpoints switching off after an address or authentication-placement change.

Where to find it

Open Settings → Integrations, select your Custom API supplier, then Technical setup and an operation. The Connection tab opens the shared address and authentication settings; Handbook → What [assistant name] does when… holds behavior overrides and also offers the operation’s Enabled control.

The technical builder keeps its own Enabled switch for integration managers; both edit the same operation. The Safety choices — Performs a real action, Ask a teammate before each call and Staff can use it too — have one editable home per person: the Handbook rule if you can edit both the Handbook and bot settings and manage integrations; otherwise Technical setup → Safety for integration managers. Other Handbook readers see the saved choices read-only. Building and testing requests requires permission to manage integrations. Editing a Handbook rule requires Handbook editing and bot-settings permission; someone without permission to see the connection’s address and sign-in details may see only those behavior controls. See permissions.

Set it up

Obtain the supplier’s request documentation and suitable test records.
Finish the shared connection settings.
Choose Add endpoint, or use Import as described below.
Give the operation a Title and a unique Tool name.
Complete the six numbered stages described under Settings.
Set Performs a real action before testing any operation that changes data.
Enter safe sample inputs and choose Run test call.
Select the response fields the bot may receive.
Review verification, instructions, any behavior override and the per-call approval choice.
Turn on Enabled only when you have reviewed the operation and its connection. A connected agent can also switch it on; it provides review links and reports the connection state and whether saved sign-in details were detected. Verify the active authentication method and its required fields yourself; a live label is not proof that the provider accepts them.

The editor saves changes automatically. Correct any save errors before leaving. A test waits for pending request edits to save; it does not test unsaved changes after a failed save.

Settings

Audience and proof

Each endpoint’s Who is this for control adds confirmed label membership beside its existing verification choices. Everyone is the audience default; Any of these or All of these combines selected labels. Both audience and proof must pass. Hidden until they qualify withholds the operation’s customer-specific instructions until both pass. Moving the proof picker here does not reset its saved requirement. Existing-item audience changes through a connected agent require an in-app access step; proof settings remain directly editable with the same permissions.

The defaults below are for Add endpoint. Imported operations and presets can supply different values, so review them individually.

Operation name and Enabled

Setting	What it does	Starting value
Title	A readable name in the operation list. If blank, the list uses Tool name.	Blank.
Tool name	The stable name used to call this operation. Use 2–61 characters: start with a lowercase English letter, then use lowercase English letters, digits or underscores. It must not duplicate another operation or a reserved tool name in your workspace.	`new_endpoint`, with a suffix when needed.
Enabled	Makes this operation available for normal chat use when its supplier connection is also enabled. It does not run the request now.	Off.

1. What it does

Description (tells the assistant when to use this tool) explains the operation’s purpose and inputs. It starts blank. Write what the request actually does and when it is relevant, not just “delivery API.” For example: “Look up a delivery by its tracking number and return its current status.”

Do not put passwords or keys in descriptions or instructions.

2. How the bot uses it

Setting	What it does	Default
Default behavior	Your guidance about when and how this operation should be used. This is separate from the request’s technical definition.	Blank.
How to read responses	Explain the supplier’s status values and response fields, including what indicates an unsuccessful business result. Maximum 2,000 characters.	Blank; no extra interpretation guidance.
Before calling, the customer must be	Sets the proof or membership requirement described below.	Anyone.
Verification lasts	Decides whether qualifying verification from an earlier conversation can count.	Any past verification.

In the operation’s Custom action rule in the Handbook, How the bot should use it is a behavior override. Nonblank override text replaces Default behavior; clearing it restores the default. It does not replace the request, description, shared fields or How to read responses. Verification controls there edit the same operation requirement, not a second independent check.

Recent real responses appears when samples exist and you can manage the integration. It shows recent replies to real chat-bound requests with their HTTP status and capture time. Operator test calls do not fill this history. A response can be marked as omitted when it could not be retained in full. Use samples to improve interpretation guidance, and treat them as potentially containing customer information. Stored authentication secrets are redacted from this history; that is not a guarantee that all personal information is removed.

Customer verification options

The selectable requirements are:

Anyone: no identity or membership prerequisite from this proof setting; a selected label audience still applies. Required inputs and any configured action approval still apply.
Resource verified: proof tied to an order or record. Custom API chat calls currently need qualifying identity-level proof for this choice too; order-only proof is not enough. Choose Verified to state that requirement clearly.
Verified: qualifying identity verification. This does not require an account in your system.
Recognized: a current match from a user source. Someone who merely typed another person’s matching phone or email can pass. Select this only if that disclosure risk is intentional.
Verified user: both qualifying verification and a current account match tied to that customer’s verified detail.

For either membership choice, select Provider or Any provider. A named provider has no fallback. With a named provider, Roles (any of) can require one of the role values it has actually reported; the same account match must satisfy the role check.

Membership choices and role edits can be disabled during rollout. Existing saved requirements still apply, and changing another field does not remove them. See User identification for setup and availability.

Any past verification accepts earlier qualifying verification that is still valid. This conversation requires it to have been obtained in the current conversation. Default (any past verification) means the first option. Some imported presets can display a numeric duration instead; this is a duration in seconds, not another verification strength.

Verification of the customer is separate from Verified identity as an input source. A required identity input still needs its particular verified value even when the operation is set to Anyone.

3. Request

Setting	What it does	Default
Method	Choose the supplier’s HTTP method: GET, POST, PUT, PATCH or DELETE.	GET.
Path template	The relative path appended to the connection’s Base URL. For `/deliveries/{tracking_number}`, add a parameter named `tracking_number` sent in Path. Do not paste a second full base address here.	`/`.
Body format	Appears for POST, PUT, PATCH and DELETE. JSON sends a JSON object; Form-encoded sends form-style name/value pairs. Match the supplier’s documentation.	JSON.

The preview shows the combined address and highlights path placeholders. Supply query values as Query parameters, not by hiding them in the path.

For JSON bodies, a parameter named customer.email builds a nested object, with email inside customer. Form-encoded bodies keep dotted names flat. A JSON POST, PUT or PATCH sends an empty object ({}) even when there are no body inputs. An explicitly configured JSON content type is kept; otherwise it uses application/json. Empty GET, DELETE and form requests send no body. Path values are encoded as one segment, so spaces and slashes in an input do not change the path structure.

Default headers and Authentication belong to the connection and apply across its operations. For a repeated header name, connection defaults take precedence over endpoint header inputs, and authentication headers take precedence over both. Query inputs replace same-name values from the connection’s base address; other base query values are kept. A query-based authentication key takes precedence over both. Change credentials in the connection’s authentication fields, not in a conversation input. See connection and authentication options.

4. Inputs

Choose Add parameter for each input the supplier expects. Use Remove parameter to remove a row. Every input needs Sent in and Filled from; neither can be omitted. A name must not have spaces before or after it.

Field	What it does	New-row default
Name	Exact name expected by the supplier. A Path input must match its placeholder, without the braces. Do not repeat a name in the same request location.	Blank.
Meaning	Plain explanation of the input, especially what should be taken from the conversation.	Blank.
Sent in	Path substitutes a placeholder; Query adds a URL query value; Header sends a request header; Body sends a body field.	Query.
Filled from	Select Static value, From the conversation or Value from omotto. Existing identity rows retain Verified identity.	From the conversation.
Type	Any (as sent) keeps the supplied kind. Choose Text, Whole number, Number or Yes/no when the receiving system expects that kind.	Any (as sent).
Value	Appears for Static value. Sends the configured fixed value rather than collecting it from chat. Whole number and Number use a numeric input; Yes/no offers Yes or No.	Not set.
Value from omotto	Pick a server-held value. Verified values are marked; as-given values show a warning.	No value selected.
Identity source	Appears on an existing Verified identity row.	Keeps the saved source.
Required	Blocks the request when a conversation, identity or code-supplied value is missing or blank. A required Static value must also be filled before enabling. Path inputs are always required, even with this switch off.	Off.

Choosing Text sends text even for a numeric input; a whole structured value becomes JSON text. Whole number, Number and Yes/no send real numbers or booleans in JSON bodies, and their text forms in other request locations. If the bot supplies a value that cannot be converted, the request is not sent. The bot gets the field name so it can correct the call. A fixed value of the wrong kind is refused when saving. Numeric fixed values above ±9,007,199,254,740,992, or decimals with more than 15 significant digits, are refused rather than rounded. Choose Text for identifiers and long numbers. An optional fixed Text value may be empty: it is sent as empty text, not omitted.

From the conversation means information supplied as a call input, not verified evidence. Use it for a delivery reference or search term only when appropriate for the supplier’s access rules.

Value from omotto uses information the server already holds, rather than asking the bot to guess it. Choose the value that belongs in the supplier’s parameter:

Conversation id or Inbox link, channel, and customer language.
Line id or name, and workspace handle or name.
Current open ticket id or Inbox link, when a ticket exists.
Customer id and name as given.
Verified customer phone or email.
Phone or email as typed — could be anyone’s. These are separate from the verified values.
Latest store order number, labelled not verified. A store lookup can use an address from the customer profile; it does not prove ownership.

For example, add external_id, choose Value from omotto, then Conversation ID. The other system receives the conversation’s stable id and can use it to avoid creating the same request twice. Do not ask the bot to invent a conversation id.

Customer names and as-typed details are not verification. A WhatsApp account handle is not a phone number. Choosing a verified value does not itself verify the customer. If a required value is unavailable, omotto does not send the request; an optional unavailable value is left out.

Existing Verified identity inputs still work: Verified phone and Verified email mean the same values as their verified catalog choices. Shopify order number keeps its store lookup behavior and is not proof of identity. Existing Matched user ID rows remain bound to the account that passed the operation’s named Provider check, under Verified user. They never use an id supplied in chat.

Adding, removing or changing a server-held input through a connected agent applies directly, just like editing it in the app. The same applies when the agent creates or imports an operation. Its result tells you which values the operation will send and to which destination. This notice does not ask for approval. Changing between equivalent legacy and new spellings does not change the data sent.

Undoing an unrelated change through a connected agent does not ask you to approve unchanged customer-verification settings again. If the undo would actually change the user-identification condition, finish that change in the app.

An operation can have up to 100 inputs. Each input name can use up to 200 stored bytes, not 200 characters. Some characters use more than one byte. If an older operation exceeds a limit, you can still change unrelated settings or turn it off; repair its inputs before changing its definition or turning it on.

Every path placeholder needs exactly one matching Path input. Keep the supplier’s exact input name, including hyphens, dots or non-English letters. Header names use English letters, digits or HTTP punctuation such as a hyphen, with no spaces, colons or non-English letters. Fixed header values cannot contain line breaks or a NUL (zero) character. Header names count as duplicates even with different capitalization. In a JSON body, do not define both a whole object such as client and a nested field such as client.email.

If staff approval is required and a server-held value changes while the request waits, omotto does not run the changed request under the old approval. It asks for a fresh proposal with the current values.

5. Test it and choose what the bot sees

Enter sample values for conversation, identity and Value from omotto inputs in Test call.
Choose Run test call.
If asked Run a REAL action?, confirm only if you intend the live change.
Inspect the HTTP status and returned field samples.
Tick each field the bot may receive.
Add an optional Label to make a selected field understandable.
Expand Raw response if you need the full returned JSON.
Use Copy JSON only when it is safe to copy that data.

Tests use the real connection and authentication. Identity values entered here are samples: a passing test does not prove the real customer has verified details or that a chat call will pass verification. Testing a write uses your explicit confirmation rather than the chat’s teammate-approval flow.

The checklist starts with no fields shared. An empty selection does not share the whole response. The bot receives the HTTP status and any interpretation guidance, but no response-body fields. This also applies to failed writes: select an error field, such as error, if the bot needs that detail. An empty selection or no matching field shares no answer body. A large or unreadable error reply can be omitted; full response samples remain restricted to integration managers. Separately, a failed real action keeps a staff-only error copy in the Inbox, with sign-in secrets and known customer details hidden, even when no fields are shared with the bot. That copy is not sent to the customer or given to the bot. Only share the data needed for the task; private notes, credentials and internal costs should stay unselected.

Nested objects expose their individual fields, such as customer.name.
Array fields offer each item or first only after selecting the field. The first shares the field across returned items; the second shares it only from item zero. It does not select the newest or best item for you.
Collections keyed by an identifier can offer per-item fields too, but not first only. Large replies can be shortened; selecting each item does not guarantee the bot receives every result in a large collection.
Nested objects inside collection items can be selected. Nested arrays are not automatically expanded into checklist fields.
A previously selected field absent from the latest response remains listed as configured, but not in this response. It is not silently removed.
For an absent or deeper field, use ＋ add a field by path (advanced), enter a path such as status, events[0].city or events[*].city, then choose Add. The last form shares city across event items. Only one all-items level is supported. Correct any displayed path error.
Selecting a whole object or array by an advanced path can share its contents, not just one leaf. Prefer individual fields when some contents are private.

Raw response inspection is for the integration manager. It does not change which fields are shared with the bot. Responses can contain customer data or information echoed by the supplier; review before copying or sending them to support.

6. Safety

Setting	What it does	Default
Performs a real action	Marks a request that changes the other system. Turn it on for creating, updating, cancelling or deleting data, regardless of Method. It does not itself require per-call approval.	Off. You must classify the operation correctly.
Ask a teammate before each call	For a real action, waits for a teammate to approve each customer-chat call. A matching pending card is retired when the bot next uses this approval-off setting; that card can no longer be approved.	Off for endpoints created from scratch. Presets and templates can carry it on; existing write endpoints kept it on.
Staff can use it too	Makes a read-only operation available in the team channel. Staff use does not require customer verification, but required identity inputs still need a usable value.	Off. Turning on Performs a real action switches this off and prevents enabling it.

Instructions are not a replacement for these switches. A POST is not automatically treated as a write, and a disabled endpoint is not a sandbox.

Ask a teammate before each call applies to this Custom API operation only. Changing it does not change approvals for the built-in Shopify shipping-address and order-contact ability, or grant that ability access to the store. Configure the built-in Shopify ability, its store policy and any required Shopify access separately; approving a Custom API call is not a substitute.

What happens when…

An operation has definition problems

The editor shows Fix this operation before the bot can use it with the affected fields. A refusal names the field, for example params[2].source, so the person configuring it can correct that input. This also applies to definitions created by a connected agent.

An operation with definition problems is not offered to the bot. Other working operations stay available. Test calls send nothing until you fix the definition; sample values cannot hide an invalid identity source. You can keep a disabled draft with a required fixed value still missing, but you must fill it before enabling. You can always turn an operation off on its own, even if its definition needs repair.

A test succeeds, fails, or the request changes

Tested means the last test returned HTTP 200–299 and its request configuration is still current. Live means the endpoint and connection are enabled; it is not a promise that testing passed. Otherwise the operation shows Draft, unless it qualifies as Tested.

Changing Method, Path template, Body format or parameters clears the old test result. Changes to the connection’s address, authentication or shared headers also invalidate affected tests. Description, behavior and response-field edits do not clear the transport test; review those separately. No successful-test requirement prevents you from switching an endpoint on.

An answered business reply such as HTTP 404 can still have useful JSON for choosing fields and interpretation. It does not earn a successful-test mark. Authentication failures, rate limits and server failures remain errors. A missing HTTP status usually means no usable service response was received.

A customer-chat write is rejected or has no answer

Approval is permission to try, not proof of success. A service rejection is recorded as not done and appears in the conversation; the bot can retry after a fix or a teammate can re-propose it. A server error is also not marked done, but check whether it partly happened before repeating.

A sent request with no answer has an unknown outcome. It may have gone through. That attempt is never re-sent automatically; a teammate checks and decides whether to approve a fresh proposal. These records also exist when per-call approval is off. See failed and uncertain actions for the full flow.

You import or export operations

Import accepts a cURL command, OpenAPI spec (OpenAPI 3, in JSON or YAML), Postman collection or omotto preset (.json). Older specifications, including Swagger 2.0, must be converted to OpenAPI 3 before importing. cURL describes a request; OpenAPI describes an interface; Postman collections group saved requests. See the official cURL manual, OpenAPI specification and Postman export guide.

Choose the import format.
Paste the source. OpenAPI and omotto presets also offer a file picker; OpenAPI also offers fetching from a URL.
Choose Preview.
Review warnings and keep only the operations you want selected.
Choose Import selected.
Review every imported operation before testing or enabling it.

An invalid omotto preset is refused before anything is imported. The error names the field to correct; omotto does not replace an unknown input source, sign-in method or verification level with a default. Masked fixed values remain disabled drafts, even when the input is optional. Fill them in and review any unbound User identification source before switching an operation on.

Imports create disabled endpoints. A new imported connection starts on if its address includes a host; a connection without a host yet starts off. It has no stored sign-in credentials; complete any required sign-in before use. Importing into an existing connection keeps that connection’s current sign-in and base address; review any address-mismatch warning.

cURL, OpenAPI and Postman imports start with no shared response fields and Performs a real action off. Correct this switch before testing a real write. Native omotto presets can preserve behavior, shared fields, identity bindings and the per-call approval choice, but their endpoints still arrive disabled. Older presets without an approval choice keep approval on for real actions.

The review lists field-specific notes below each operation. Notes for requests skipped from the collection appear above the list. Each note keeps its field address and item-specific detail alongside its translated label, so you can identify the affected input. A note such as params[2].source gives the field address. Review these notes before choosing Import selected; they describe changes, not an automatic repair.

Fill in headers and any identity input changed to a fixed value. Check added path inputs and any input moved to the query.
Add omitted cookie or body information by hand if the request needs it. Requests on a different scheme, host or port need their own connection.
Review arrays, deeply nested objects and empty values: these become text. Long or highly precise numbers also become text to preserve every digit.
For native omotto presets, reconnect any user-account input or requirement to this workspace’s User identification setup before enabling.

Postman variables become inputs named after the field the request sends: email={{customer_email}} becomes an input named email, not customer_email. Header variables also keep the exact outgoing header name, for example X-Customer, with the variable name in the description. JSON numbers and yes/no values keep their types, including numeric examples inside arrays or deeply nested objects shown as text. OpenAPI imports keep nested required fields and use the operation’s parameter definition when it overrides a shared one. cURL supports --data-urlencode and keeps multiple data fields; data implies POST unless the command specifies another method.

Export preset exports reusable configuration without the connection’s stored authentication credentials. It can still contain static input values, default headers, addresses and instruction text. Review the file before sharing it. Do not assume arbitrary secrets pasted into those places are removed. Likewise, remove unnecessary secrets and personal data from source material before importing; import is not a universal secret scrubber.

You remove an operation

Use More actions → Remove endpoint and confirm. Removal cannot be undone. If it is selected as a User identification source, choose another source first.

Troubleshooting

Symptom	What to check
Missing input or a path error	Match every `{placeholder}` to a Path parameter with the same name. Supply required sample values. Check Sent in and Filled from.
Connection configuration error	Open Manage connection and correct saved default headers, the authentication header name or sign-in values. Header names cannot contain spaces or line breaks; values cannot contain line breaks or null characters. Changing sample inputs does not fix saved connection settings.
Authentication failed, HTTP 401 or 403	Check the connection’s status. Needs you points to credential recovery: re-enter the correct details or run a successful test with the current details. Check the authentication method, header/query name and supplier permissions. A 403 alone does not mark the connection as broken; it can mean this particular operation is not allowed. Re-enter credentials after importing a new connection or changing its authentication type; changing the type clears saved credentials.
Wrong route or unexpected business result	Check the combined base address and path, method and body format. Read the supplier’s reply and document its business meaning under How to read responses.
Test works but customer calls cannot run	Sample identity values bypass customer verification in the test. Check the real customer’s verified phone/email, verification freshness and required identity inputs. Do not weaken private-data checks just to make a test pass.
Bot gets no useful response data	Tick fields in the checklist. Check actual response paths, missing fields and each-item versus first-only mode. Writing interpretation guidance does not share unselected data.
Operation is not available	Check both Enabled switches. A successful test alone does not enable anything. Check Staff can use it too for team-channel use.
Address blocked or service unreachable	Ask the supplier for its supported public HTTPS address and check service availability. Contact support if a documented public address remains blocked.

For support, share the operation title, approximate test time, HTTP status and a redacted description of the problem. Do not send authentication secrets or unreviewed raw customer responses.