Connect your own system with Custom API

Custom API connects omotto to a system your business uses, such as a delivery service or your own customer database. An API is a way for two systems to exchange requests and information. You can manage a prepared connection without programming; building the requests usually needs the system’s documentation and someone who understands it.

How it works

There are two parts:

A connection holds the system’s address and shared sign-in details.
An endpoint is one operation at that address, such as looking up a delivery or requesting a cancellation. One connection can have several endpoints.

A connection and each endpoint have separate on/off switches. Both must be on for an operation to be available in customer chats. New connections start on when created with a complete host address, including imports and omotto presets. A draft with only https:// starts off and must be switched on after you complete it. New endpoints always start off. Nothing runs through them until they are switched on; the connection also needs the required sign-in details. You can turn the connection on before saving all the required credentials, but its operations will not be offered to the bot yet.

A lookup returns information. An endpoint marked Performs a real action changes something in the other system. For each real action, you choose whether to turn on Ask a teammate before each call. It is off for endpoints created from scratch. Imported presets and templates can carry approval on. Existing write endpoints kept approval on when this choice was introduced. The person building the endpoint must mark it correctly; omotto does not infer whether a request makes a change.

Read-only endpoints can also be offered to the team channel with Staff can use it too. This is off by default and is not available for real-action endpoints.

Automations can call these operations from a saved rule rather than waiting for the bot to decide during a chat. An automation’s saved setup authorizes its real actions; it does not open a separate chat approval for each call. Review automation actions separately.

For AI help building the connection, use a connected agent. It can prepare connections and endpoints, subject to your permissions. Its new connections follow the same defaults above; endpoints start off. The agent can switch endpoints on with your permissions. It clearly warns when something is not yet live and provides links so you can review each item first. If the connection is off or sign-in details are missing, switching on an endpoint alone does not make it operational. The Coach inside omotto does not build Custom API connections; it refers you to the connected agent route. Enter third-party passwords and keys inside omotto, not in a conversation with an agent.

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.

Changing a connection’s base address (even only its path), token address, authentication method, header/query name or client-authentication style removes its saved sign-in credentials, cached token, secret request headers and fixed secret input values on its endpoints. Input names and positions stay. Affected endpoints switch off and stay off until you re-enter those values in omotto and switch them back on. A relative path change on one endpoint does not trigger this removal. In the app, choose Save connection changes and review Remove stored secrets and save? before Save and remove secrets; Cancel keeps the saved values. After saving, the result lists what was removed and links to re-enter it. A connected agent warns you beforehand with the exact secret fields and endpoints; it applies the change directly, without a separate approval step. If an address itself contains a removed secret, that address is cleared too even if it would stay masked and the connection switches off. The warning and result name the address fields to re-enter before switching it back on. If an endpoint path carries a removed secret, its fixed path text is cleared too, keeping only its input placeholders; that endpoint switches off. The confirmation and result identify the endpoint and its path_template field. Re-enter the correct path before switching it back on.

Rare recovery case: if an existing saved secret is damaged and cannot be decrypted, the confirmation explains a broader reset: all addresses and fixed endpoint paths are cleared and the connection switches off, preserving input placeholders. Re-enter safe addresses and sign-in details before enabling it again. This happens only after an actual stored-secret decryption failure—not for ordinary edits, missing secrets, masked values or a normal validation error.

Where to find it

Open Settings → Integrations → Add integration. On the Custom API card, choose Add supplier. Existing connections appear under Settings → Integrations by their name. Within a connection, use Technical setup to build operations and Connection to edit the address and sign-in details. Handbook → What [assistant name] does when… enables operations and adjusts their behavior. An operation that requires approval shows a read-only notice on its rule; there is no separate Custom API Policy page.

Creating connections and editing requests require integration-management permissions. Behavior controls have their own permission checks; if a control is missing or read-only, ask your workspace administrator.

Set it up

Required for a bot call: a connection with the correct address and authentication settings, plus at least one configured endpoint. Both the connection and that endpoint must be enabled for ordinary chat use. Mark requests that change data as Performs a real action, then choose whether to turn on Ask a teammate before each call.

Choose one starting route: build from scratch, use a template or import a prepared setup. These are alternatives. Testing sends a real request and is optional; use safe sample data if you choose it. Additional endpoints and staff access are choices, not requirements.

Before you begin

Ask whoever maintains the other system for its public HTTPS address, its sign-in method and its documentation or a prepared file to import.
You need permission to manage integrations in the right workspace. Ask your workspace owner to check your permissions if the controls are missing.
Decide which operations only look something up and which change something. A change should be marked Performs a real action.
Use sample data and, if possible, a test setup of the other system. A test contacts the real system.

Start from scratch

In the add menu, choose From scratch.
Replace Name with a name your team will recognize.
Replace Base URL with the public HTTPS address supplied by the system’s provider. The starting https:// is only a placeholder.
Choose Authentication according to that provider’s instructions.
Enter the required sign-in fields explained below.
Add Default headers only if the provider asks for them.
Prepare the operations using the endpoint builder guide, or have your connected agent prepare them.
Review each operation’s inputs, customer-verification requirement, real-action setting, per-call approval choice and shared response fields.
Run a test with suitable sample data. A test contacts the real system, even while the connection or endpoint is off. A test of a real action can make a real change.
Check the connection’s Enabled switch. Turn it on if it is still off after you complete the address and sign-in details. Turning it on is allowed before saving credentials, but the bot cannot use its operations until every credential for the selected method is saved in Manage connection.
Turn on Enabled for each endpoint you want available.

Connection edits save automatically. Secret fields save after you leave the field with a complete credential filled in. For HTTP Basic, fill in both Username and Password; for OAuth2 (client credentials), fill in both Client ID and Client secret. A partly filled pair is not saved.

Start from a template

In the add menu, look under From a template.
Choose a template. Order tracking (generic) is a starting example, not a ready connection to a particular delivery company.
Review the prepared endpoints.
Complete the real address and sign-in details on the connection.
Review the operations before turning on both levels of switches. You can test with safe sample data if you want to check the real response.

A template creates off endpoints. Its connection starts on if it has a complete host address, or off if its address is still a placeholder. Its example paths and shared response fields must match your provider’s actual service.

Import a prepared setup

Import means copying a prepared description of requests into omotto. It is a one-time copy, not ongoing synchronization with the original file.

Fetching a specification from a link is capped at 2 MB. Use a public HTTPS link that opens the file directly; links that redirect elsewhere are refused. If the file is larger, ask your technical helper for a smaller specification.

Choose Import (cURL / OpenAPI / Postman)… in the add menu. To add operations to an existing connection, use Import on its Endpoints tab instead.
Choose the source format from the table below.
Fill in Paste it here, or use one of the alternatives available for that format.
Click Preview.
Read the warnings and check the listed requests. All are selected initially; clear any you do not want.
Click Import selected.
Review the imported endpoints before enabling them. A real test call is optional.

Import choice	What to provide
cURL command	Paste a command describing a request, supplied by whoever maintains the other system.
OpenAPI spec	A version 3 description of the service, in JSON or YAML. Paste it, use …or fetch from a URL (OpenAPI), or …or pick a file.
Postman collection	Paste the JSON contents of a collection of prepared requests.
omotto preset (.json)	Paste or pick a file previously exported from omotto. It carries omotto-specific behavior and safety settings as well as the requests.

JSON and YAML are file formats. Ask whoever maintains the system for a suitable file; you do not have to write one yourself.

The import picker starts with cURL command when opened from the add menu. The file picker is offered for OpenAPI and omotto presets, not for cURL or Postman. If you fill the URL field, that URL is used instead of the pasted text; clear it to use the text.

A new imported connection has no saved authentication credentials. It starts on if its address includes a host; a connection without a host yet starts off. All imported endpoints start off. Enter any required sign-in details before use. Importing into an existing connection keeps that connection’s name, address, sign-in and on/off state unchanged. Only the new endpoints are off. A warning appears if the source address differs; the operations will use the existing connection’s address and credentials when enabled.

External imports do not choose which returned fields to share, do not mark requests as real actions, and do not establish verified-customer input bindings. Those need human review. In particular, a request that changes data may import with Performs a real action off: correct it before testing or enabling it. An omotto preset preserves those settings and its per-call approval choice, but still needs review for your business. Older omotto presets without an approval choice keep approval on for real actions. User-account requirements tied to another workspace need to be linked to your own User identification setup before enablement.

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.

Do not assume an imported file is free of private information. Request bodies, fixed inputs or headers can contain sensitive values even when no authentication credential is saved.

Define an endpoint the bot can call

Use this for a new connection or to review an imported operation. Ask the other system’s maintainer to help with request fields if needed.

Choose Add endpoint, or open an imported endpoint.
Set its Title and unique Tool name.
Describe what the operation does and when to use it in Description (tells the assistant when to use this tool).
Match Method and Path template to the provider’s request documentation. The path is relative to the connection’s Base URL.
Define the request’s inputs, including any required path, query or body values.
Review Before calling, the customer must be for customer verification.
Turn on Performs a real action if the request changes data. Turn on Ask a teammate before each call separately if a teammate should approve each customer-chat call. The request method alone does not choose either setting.
Optional: choose Run test call with safe sample inputs. This is a real request, not an approval-protected customer-chat call.
Configure only the returned fields that the bot may receive. Select them from a safe test response, or use ＋ add a field by path (advanced) with field paths confirmed by the provider.
Turn on the endpoint’s Enabled switch when you want to make the reviewed operation available.

Also enable the parent connection for ordinary chat use. The endpoint builder guide explains the request fields and response-sharing controls in detail. If you cannot supply or confirm the request details, keep the endpoint off and ask the system’s maintainer; a saved connection alone is not enough.

Optional: check the behavior you chose

Test each endpoint with sample data and check the result matches the other system.
Check that the connection’s Enabled switch and each endpoint’s Enabled switch are on.
Open each operation’s rule in the Handbook and review its per-call approval choice. Integration-only managers can change it in Technical setup → Safety.
Try the operation in a rehearsal. Read the rehearsal guide first: with Real writes, actions can really happen.

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.

Connection settings

These defaults describe From scratch. Templates and imports can supply different starting values.

Setting	What it does	Starting value
Name	Names the connection in omotto.	New supplier, with a number added if needed.
Base URL	The shared address to which operation paths are added. Use the address from your provider, including any required base path.	`https://`, an incomplete placeholder.
Enabled	Allows its enabled endpoints to be offered to the bot once the selected authentication method’s credentials are saved. Turning it off stops availability without deleting the setup. Missing credentials do not prevent turning it on.	On when created with a host address, including imports; off while no host is present, such as the incomplete `https://` draft. Completing an existing draft does not switch it on for you.
Authentication	How omotto identifies your business to the other system. This is different from verifying a customer.	Bearer token.
Default headers	Extra named details sent with every request, such as an accepted response format or service version. Names must be valid header names, such as `Accept` or `X-Api-Version`, without spaces or line breaks. Values must not contain line breaks or null characters. Invalid edits are not saved. Add header adds a name/value pair; Remove header removes it.	Empty.

Use the dedicated authentication fields for keys and passwords. Default headers are not a password vault: their values are visible in settings and travel in an in-app preset export. If a request and the connection specify the same header, the connection default wins; authentication headers take precedence over both.

Authentication: all choices and their fields

Choose the method the provider documents. A header is a named detail attached to a request; a query parameter is a named value attached to its address. Header / query name is the exact name the provider requires, not your own label. It starts empty, even when an example is shown in the field.

Authentication choice	Fields and meaning
None (no auth)	Adds no connection-level sign-in. No credential fields appear. Use only when the service’s setup calls for this.
API key (header)	Header / query name is the header’s name. Secret is the provider’s key.
API key (query param)	The same two fields, but the key is sent in the request address instead of a header.
Bearer token	Secret holds the access token, a private code issued by the provider. omotto adds the Bearer sign-in header.
HTTP Basic	Username and Password hold the provider’s sign-in pair. Enter both when replacing it.
Custom header	Header / query name names the header. Header value is its complete fixed value, exactly as supplied by the provider.
OAuth2 (client credentials)	omotto obtains an access token using your service credentials. This is a system-to-system flow, not a customer login or a browser sign-in popup. Complete the additional fields below.

New credential fields start empty. A secret field shows •••••• when that field has a saved value; the dots are a placeholder, not the secret. Saved authentication credentials are encrypted and are not shown back to you. A secret is stored. Enter a new one to replace it. means that field has a saved secret. Leaving the credential fields blank keeps it only while the destination and authentication placement stay unchanged. See the connection-editing warning above before changing either. Changing Authentication clears the saved credentials, including when switching between the two API-key choices or to None (no auth). Enter replacement details for the new method before testing or using it.

For the bot to use the connection, save Secret for Bearer token or either API key method; Username and Password for HTTP Basic; Header value for Custom header; or Client ID and Client secret for OAuth2. None (no auth) needs no credentials. A saved credential from another authentication method does not complete the selected method. Sign-in values cannot contain line breaks or null characters. For header authentication, Header / query name must also be a valid header name without spaces or line breaks.

OAuth2 (client credentials)

Here, “client” means your service application, not a customer of your business.

Setting	What it does	Starting value
Token URL	The provider’s public HTTPS address for obtaining an access token. This may differ from the connection’s base address.	Empty; required for this method.
Scope	The provider’s requested access names, exactly as documented.	Empty; optional.
Client authentication	HTTP Basic sends the client credentials as a sign-in header. In request body sends them inside the token request. Choose what the provider supports.	HTTP Basic.
Client ID	Identifies your service application to the provider. Enter together with its secret.	Empty.
Client secret	The private credential for that application.	Empty.

omotto reuses the access token and obtains a new one when needed. Replacing the client credentials discards the old saved token. You do not need to copy tokens into the connection by hand for this method.

Custom action: enablement, behavior and customer verification

Each endpoint has its own Custom action rule in the Handbook. Open its row to see the behavior and verification fields. Readers can inspect effective instructions without edit controls. Editing there requires Handbook editing and bot-settings permission; it does not require access to the connection’s address and sign-in details. Edit request & test opens the technical builder when your permissions allow it. Old Capabilities and Policy bookmarks now hand off to the available Handbook or Technical setup home.

Setting	What it does	New-endpoint default
Enabled	Enables this endpoint. The connection must also be on. This is the same endpoint switch as the one on the endpoints list, not a third switch.	Off.
How the bot should use it	Your guidance on when and how to use the operation. Your text overrides its prepared Default behavior. Clearing your override restores that default.	No override; the prepared default is used if one exists.
Before calling, the customer must be	Chooses Anyone, Resource verified or Verified. With user-source setup and rollout availability, also offers Recognized and Verified user, a Provider, and optional Roles (any of).	Anyone.
Verification lasts	Any past verification accepts a still-valid earlier proof. This conversation requires proof from the current conversation. An imported preset may also show a numeric duration, measured in seconds.	Any past verification.

Anyone removes this proof setting’s customer-proof and membership requirement, not a separate selected label audience; it does not remove sign-in to the other system or fill required identity inputs. Verified requires qualifying identity verification, not membership. Recognized accepts a current account match even if the matching detail was merely typed; Verified user also requires qualifying verification tied to the match. A named Provider and optional roles restrict which match can count. Resource verified remains separate and currently needs identity-level proof in Custom API chat calls; order-only proof is not enough.

New membership choices can be disabled during rollout. Requirements already saved remain enforced. Have the builder review both the requirement and the source of each customer input. Matched user ID, when available, supplies the account selected by the operation’s own Verified user check for the same named source, not an id typed in chat. See membership setup and endpoint safety and inputs.

Behavior text does not change the per-call approval choice or customer-verification controls. The Handbook rule shows the saved choice. With Handbook, bot-settings and integration editing permissions, open its editor and use Ask a teammate before each call under Performs a real action. Integration-only managers use the same controls in Technical setup → Safety, never both homes for the same person. A connected agent can also change this choice with your permissions. When the bot next uses the operation without per-call approval, a matching pending card is retired and can no longer be approved. The call can then proceed under the current setting.

These enablement and per-call approval choices belong to the Custom API operation you are configuring, not to every action the bot can perform. The built-in Shopify shipping-address and order-contact corrections have their own ability switch, store policy and Shopify access requirements. Turning on a Custom API connection or approving one of its calls does not enable that built-in Shopify ability or grant its store access. Enabling the Shopify ability does not switch on a Custom API operation either.

What to configure next

Choose only the options that fit what you want this feature to do.

Add the remaining operations with the endpoint builder guide.
Review which response fields are shared with customers.
Set up User identification if an operation must be limited to the verified customer.
Use automations when an operation should run on a rule, then go live.

What happens when…

I switch something off?

Turning off the connection makes all its operations unavailable. Turning off one endpoint leaves the others available if their switches and the connection are on. Settings remain saved. These switches are not a way to undo an action already performed in the other system.

What does the connection status mean?

Status	Meaning	What to do
Working	The connection is on, its selected sign-in details are saved, and at least one endpoint is on. No credential failure is currently recorded.	Test the operations before relying on them. This status is not a live availability check of the supplier.
Needs setup	Sign-in details are missing, or no endpoint is on. Missing sign-in fields are listed beside the status.	Add those details in Manage connection, then review and enable the endpoints you need.
Needs you	The supplier rejected the connection’s credentials during a bot call or an operator test.	Follow the status link. Re-enter the correct credentials, or run a successful endpoint test started during that incident with the current details.
Off	The connection’s switch is off.	Review its setup before turning it on.

When a previously connected supplier definitively rejects its credentials, omotto sends a Your [supplier name] connection is broken notification. Repeated failures in the same incident do not keep sending it. A later successful bot call can restore the connection automatically. If it breaks again shortly after an automatic recovery, use the recovery steps above rather than waiting: automatic recovery is damped for 24 hours. The status itself does not remove an otherwise configured tool from the bot.

Connection health is tracked only for a connection-level authentication method. None (no auth) does not mark the shared connection as broken or recovered when a request succeeds or is rejected, including when you put sign-in details in Default headers. This avoids treating one customer’s temporary request token as a failure for everyone. A failed first test of a pending draft reports its error in the test pane without a broken-connection notification.

I see Draft, Tested or Live?

Draft means the operation is not live and has no current successful test stamp. Tested ✓ means a test succeeded, but the operation is still not live. Live means both on/off switches are on; it is not a guarantee that the last test succeeded or the provider is currently reachable. Changing request details or connection sign-in can clear an earlier test stamp.

Only the chosen Shared response fields are passed to the bot. With no fields selected, none of the returned data is shared. The person configuring the operation can see a fuller response during testing. This selection also controls error details: select the provider’s error field, such as error, if the bot needs that reason. Empty selections or fields missing from the reply share no answer body. Larger or unreadable error replies may be omitted. Full redacted samples remain available to people allowed to manage the integration, not automatically to the bot. Review these choices before enabling any operation; the endpoint guide explains the checklist.

A real action fails or has no answer?

Only a successful service reply records the write as done. If the service rejects the request, it is recorded as not done, even if a teammate approved it. Staff see the failed action in the conversation. The bot can try again after a fix, or a teammate can re-propose the action. A request that never left omotto is also recorded as not sent, not completed.

If the service reports a server error, the action is not marked done. Check the other system before repeating it if it could have partly happened.

If the request was sent but no answer came back, its outcome is unknown: it may have happened. omotto never re-sends that uncertain attempt automatically. A teammate must check the other system and decide what to do. A fresh proposal can be reviewed and approved; it does not replay the old attempt.

These outcomes are recorded whether per-call approval is on or off. Open Service response details on the failed-action note in the Inbox for the saved staff-only error copy. Stored sign-in secrets and known customer details are hidden. Your team can see this copy even with no shared response fields selected; the bot cannot. It also appears in the internal channel and its connected staff notification. A missing, oversized or unsafe-to-decode error body is omitted with a notice. Internal error details are not a customer reply; the bot should explain only that the action could not be completed or is being checked.

I want to export or remove the connection?

Export preset downloads a JSON file with the connection and its endpoint setup. Saved authentication credentials and saved access tokens are excluded. Default headers and fixed input values are included, so inspect the file before sharing it. Re-importing the file leaves endpoints off. A new connection with a complete host address starts on, but its required authentication credentials must be entered again; it is not a ready-to-run copy.

Remove asks for confirmation and deletes the connection and its endpoints. Switch it off instead if you only want to pause it. Removal is refused if an endpoint is selected as a user provider; choose a different provider setup first.

Troubleshooting

I cannot see the creation or editing controls. Ask an administrator to check your permissions. Request editing and capability editing are separate permissions.
The address is rejected. Check the full public HTTPS address with the provider. Private-network and local-computer addresses are not accepted. For an OpenAPI URL, use a directly accessible document; a sign-in page is not a specification.
Preview cannot read the input. Check the selected format. Use OpenAPI version 3, a Postman collection rather than a single response, or an exported omotto preset. Read preview warnings before importing.
Sign-in fails. Check the authentication method, exact header/query name and provider credentials. For Basic or OAuth2, enter the complete pair. A stored-secret hint confirms storage, not that the provider accepted it. Run a new test.
An operation is on but unavailable. Check the connection switch and save every credential required by the selected authentication method in Manage connection. A saved-secret hint alone does not prove that method is complete. If the endpoint editor lists definition problems, fix the named input fields first; an operation with those problems is not offered to the bot. See input setup and definition problems. Then review the customer’s verification requirement and any required verified inputs. Team-channel use also needs the read-only staff option.
A real action failed or its outcome is unknown. Read the conversation note. Fix a rejected request before trying again; check the other system before any new attempt after a server error or unknown outcome.
The test reports a connection configuration error. Review the saved default headers, authentication header name and sign-in values. Remove spaces from header names and remove line breaks or null characters from values. Use the provider’s exact details; changing the operation’s sample inputs will not repair saved connection settings.
The request succeeds but no useful data appears. Check Shared response fields against the actual response and review How to read responses in the endpoint builder.
An imported preset cannot be enabled. Review any user-provider requirement that needs rebinding to this workspace. Do not weaken the requirement just to clear an error.
Still stuck? Contact omotto support with the connection name, operation name and error shown. Do not send passwords, private keys or an unreviewed preset file.

Keep server-held inputs when moving a setup

Exporting and re-importing an omotto preset preserves Value from omotto mappings, such as a conversation id. These inputs use server-held values, not a guess from the bot. Review verified versus as-typed details in endpoint inputs. Through a connected agent, importing an endpoint with a server-held input applies directly, like editing it in the app. The result names the values and their destination without asking for approval.